{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "The story for multi-directory support"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "###Our original goals...\n",
      "* Multi-directory support/navigation in the dashboard\n",
      "* Get rid of notebook IDs\n",
      "\n",
      "####and here is what happened...\n",
      "1. Get rid of notebook IDs; rather identify a notebook by its name and path.\n",
      "2. Decouple the notebook from kernels.\n",
      "3. We found it was necessary to redesign out URL mapping scheme and web service design.\n",
      "5. Allow client to change directories in dashboard and open notebooks buried in sub-directories.\n",
      "4. Introduce the concept of a 'session' to map a kernel to an ID.\n",
      "6. Standardize the body sent with HTTP requests between client and server."
     ]
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Our Solutions..."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## 1. Get rid of notebook IDs\n",
      "* Currently, notebook uses UUID as an immutable identification label"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "* What URL is easier for users?\n",
      "\n",
      "<pre>127.0.0.1:8888/notebooks/foo/bar/notebook.ipynb</pre>\n",
      "\n",
      "-------------------  OR  ------------------------\n",
      "\n",
      "\n",
      "<pre>127.0.0.1:8888/1e71fb36-7cee-43f0-99d4-ddf099906460</pre>\n",
      "\n",
      "* We are completely moving away from UUIDs in the notebook, and now identify/open a notebook using its name and path in the URL (starting from the location where the server is started).\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## 2. Decouple notebook from kernel (vice versa)\n",
      "* Currently, the notebook and kernels are entangled... The notebook_id was passed to the kernel manager as a parameter in the URL and stored in a kernel mapping dictionary.\n",
      "* All this mapping is stored in another service, known as a session (see below).\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "##3. URL scheme/web service design\n",
      "* Currently, we aren't very consistent on following RESTful web services\n",
      "* New design and structure follows strict RESTful web service design\n",
      "    * RESTful requests\n",
      "        * GET\n",
      "        * POST\n",
      "        * PUT\n",
      "        * PATCH ~ note: notebook renames use this now\n",
      "        * DELETE\n",
      "    * New services at these URLs:\n",
      "        1. ```/notebooks/notebook.ipynb``` - live html notebook\n",
      "        2. ```/tree``` - dashboard URL\n",
      "    * New API web service URLs:\n",
      "        1. ```/api/notebooks``` - handles notebook managing and requests\n",
      "        2. ```/api/kernels``` - handles kernel and websocket requests\n",
      "        3. ```/api/sessions``` - handles mapping between notebook and kernel\n",
      "        4. ```/api/contents``` - handles requests to other files that are not notebooks and sub-directories\n",
      "* See full documentation <a href = \"https://github.com/ipython/ipython/wiki/IPEP-16%3A-Notebook-multi-directory-dashboard-and-URL-mapping\">here</a>"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "##4. Sub-directory in 'notebooks' and 'tree' web services\n",
      "* FINALLY, multi-directory support!\n",
      "* Open up the dashboard in a sub-directory/folder\n",
      "    <pre>/tree/path/to/folder</pre>\n",
      "* Open up a notebook that's found in a sub-directory/folder\n",
      "    <pre>/notebooks/path/to/notebook/Untitled0.ipynb</pre>\n",
      "* Also, the API web services use this path-to-file URL scheme\n",
      "    <pre>/api/notebooks/path/to/notebook/Untitled0.ipynb</pre>\n",
      "    <pre>/api/contents/path/to/notebook/example.txt</pre>\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "##5. Sessions\n",
      "* Introducing the sessions web service API.\n",
      "* A session takes a notebook, lauches a kernel, and stores the mapping between the two.\n",
      "* This is the true solution to decoupling the notebook from the kernel.\n",
      "* Everytime a notebook is opened, a session is created and a kernel is started. Deleting a session will shutdown the kernel. "
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "##6. Standardized a model for request data\n",
      "* When an HTTP request is made between client and server, the json data sent across needs a standard model for each web service.\n",
      "* Let's follow Github's style.\n",
      "* See the example <a href=\"http://127.0.0.1:8888/notebooks/Web%20service%20design.ipynb\">here</a>"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}