IPython's new web-service documentation

webservicedoc.md

IPython Web Services

This documentation describes the current API for IPython Notebook's web-services. In handling HTTP request, we pass all information between the server and client using JSON standard models. Each standard model is shown at the beginning of the sections below. This format adheres to the principles described in RESTful web-services.

• Notebooks
  • List notebooks in root directory
  • Create new notebook
  • List notebooks in named directory
  • Open the named noteboko in subdirectory
  • Change notebook's standard model and save modified notebook
  • Delete a notebook in subdirectory
• Sessions
  • List all sessions
  • Create a session
  • Get session information
  • Make changes to a session
  • Delete a session/kill kernel
• Kernels
  • List active kernels
  • Start a kernel
  • Shutdown a kernel
• Contents

Notebooks

This web-service handles all HTTP requests on ".ipynb" files. The standard notebooks model in JSON is shown below:

{
	"name": "Untitled0.ipynb",
	"path": "/",
	"modified": "date",
	"created": "date",
	"content":{
		"metadata":{},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}	

List notebooks in the root directory

GET /api/notebooks

Response

Returns a list of standard notebook models in the root directory.

[	
	{
		"name": "notebook1.ipynb",
		"path": "/",
		"modified": "date",
		"created": "date",
		"content":{
			"metadata":{},
			"nbformat": 3,
			"nbformat_minor": 0,
			"worksheets": []
		}
	},
	{
		"name": "notebook2.ipynb",
		"path": "/",
		"modified": "date",
		"created": "date",
		"content":{
			"metadata":{},
			"nbformat": 3,
			"nbformat_minor": 0,
			"worksheets": []
		}
	}
]

Create new notebook

POST /api/notebooks

Response

Creates a new notebook and names it with "Untitled#.ipynb" with some incremented number. Returns the JSON model of the created notebook.

{
	"name": "Untitled0.ipynb",
	"path": "/",
	"modified": "date",
	"created": "date",
	"content":{
		"metadata":{},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}

List notebooks in the named directory

GET /api/notebooks/foo/bar/

Response

Returns a list of standard notebook models in the "/foo/bar/" directory.

[	
	{
		"name": "notebook1.ipynb",
		"path": "/foo/bar/",
		"modified": "date",
		"created": "date",
		"content":{
			"metadata":{},
			"nbformat": 3,
			"nbformat_minor": 0,
			"worksheets": []
		}
	},
	{
		"name": "notebook2.ipynb",
		"path": "/foo/bar/",
		"modified": "date",
		"created": "date",
		"content":{
			"metadata":{},
			"nbformat": 3,
			"nbformat_minor": 0,
			"worksheets": []
		}
	}
]

Open the named notebook (in any subdirectory)

GET /api/notebooks/foo/bar/notebook1.ipynb

Response

Returns the standard notebook model for that named notebook and "content" value is used to display the html representation of the notebook:

{
	"name": "notebook1.ipynb",
	"path": "/foo/bar/",
	"modified": "date",
	"created": "date",
	"content":{
		"metadata":{},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}

Changing a notebook's standard model and saving modified notebooks

PATCH /api/notebooks/foo/bar/notebook1.ipynb

Response

Changes values of the standard notebook model for the named notebook and keep all unchanged keys. If the contents of the notebook are changed or modified, this is the HTTP request to save notebook's changes.

{
	"name": "notebook1.ipynb",
	"path": "/foo/bar/",
	"modified": "new_date",
	"created": "date",
	"content":{
		"metadata":{"new content"},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}

The standard model can be changed using a PUT HTTP request, but all unchanged keys are deleted.

PUT /api/notebooks/foo/bar/notebook1.ipynb

Response

Changes values of the standard notebook model for the named notebook and keep all unchanged keys:

{
	"name": "notebook1.ipynb",
	"path": "/foo/bar/",
	"modified": "new_date",
	"created": "date",
	"content":{
		"metadata":{"new content"},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}

Delete a notebook in a named subdirectory

DELETE /api/notebooks/foo/bar/notebook1.ipynb

Response

Deletes the notebook's standard model from the named location.

Contents

The contents webservice is designed to deal with HTTP requests on items other than IPython notebooks (i.e. files and folders within the user's filesystem). This webservice will eventually include a text editor for files that are not notebooks. The standard model for the contents webservice is shown below:

{
	"name": "file.txt",
	"path": "/my/path",
	"content": "..content of file..",
	"type": (file|dir|etc),
	"size": 2345,
	"encoding": "base64",
	"modified": "date",
	"created": {}
}

Sessions

A session maps a notebook to a kernel. When a notebook is opened, a session is created and a kernel is started. The standard model for a session is shown below:

{
	"session_id": "d7753a2c-14da-4ae9-95b8-7b96b11aebe7",
	"notebook_name": "notebook1.ipynb", 
	"notebook_path": "/foo/bar/",
	"kernel": {
		"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
		"ws_url": "ws://myhost/foo/bar"
	}
}

List all sessions

GET /api/sessions

Response

Returns a list of standard session models.

[
	{
		"session_id": "d7753a2c-14da-4ae9-95b8-7b96b11aebe7",
		"notebook_name": "notebook1.ipynb", 
		"notebook_path": "/foo/bar/",
		"kernel": {
			"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
			"ws_url": "ws://myhost/foo/bar"
		}
	},
	{
		"session_id": "b4dfa62c-0e91-4111-9d1f-0c59069c6602",
		"notebook_name": "notebook1.ipynb", 
		"notebook_path": "/foo/bar/",
		"kernel": {
			"kernel_id": "4adcb1a3-2e7f-4e82-af2e-d76f5815467a",
			"ws_url": "ws://myhost/foo/bar"
		}
	}
]

Create a session

POST /api/sessions

Input

Requires a JSON standard notebook model to be sent to the server before a session is created.

{
	"name": "Untitled0.ipynb",
	"path": "/foo/bar/",
	"modified": "date",
	"created": "date",
	"content":{
		"metadata":{},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}

Response

{
	"session_id": "d7753a2c-14da-4ae9-95b8-7b96b11aebe7",
	"notebook_name": "Untitled0.ipynb", 
	"notebook_path": "/foo/bar/",
	"kernel": {
		"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
		"ws_url": "ws://myhost/foo/bar"
	}
}

Get Session information

GET /api/sessions/d7753a2c-14da-4ae9-95b8-7b96b11aebe7

Response

{
	"session_id": "d7753a2c-14da-4ae9-95b8-7b96b11aebe7",
	"notebook_name": "notebook1.ipynb", 
	"notebook_path": "/foo/bar/",
	"kernel": {
		"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
		"ws_url": "ws://myhost/foo/bar"
	}
}

Make changes to a session

This can be used to rename the notebook, or move a file to a new directory.

PUT /api/sessions/d7753a2c-14da-4ae9-95b8-7b96b11aebe7

Input

{
	"name": "new_name.ipynb",
	"path": "/foo/bar/",
	"modified": "date",
	"created": "date",
	"content":{
		"metadata":{},
		"nbformat": 3,
		"nbformat_minor": 0,
		"worksheets": []
	}
}

Response

{
	"session_id": "d7753a2c-14da-4ae9-95b8-7b96b11aebe7",
	"notebook_name": "new_name.ipynb", 
	"notebook_path": "/foo/bar/",
	"kernel": {
		"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
		"ws_url": "ws://myhost/foo/bar"
	}
}

Delete a session and kill the kernel

DELETE /api/sessions/d7753a2c-14da-4ae9-95b8-7b96b11aebe7

Response

Deletes the sessions and kills the kernel held in the session.

Kernels

This webservice managers all running kernels. The standard kernel model in JSON is shown below:

{
	"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
	"ws_url": "ws://myhost/"
}

List the kernels

GET /api/kernels

Response

[
	{
		"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
		"ws_url": "ws://myhost/"
	},
	{
		"kernel_id": "4f567fb0-2455-4bc9-a137-69daac27e9a2",
		"ws_url": "ws://myhost/"
	}
]

Start a kernel

POST /api/kernels

Response

Starts a kernel and returns:

{
	"kernel_id": "b7e1a137-a434-4598-846e-ee51fb06c306",
	"ws_url": "ws://myhost/"
}

Shutdown the kernel

DELETE /api/kernels/0899e220-ab81-43c2-a97a-ff1af4118598

Response

Kills the kernel and deletes the ID.