From 11ae4d7ff51a04ea4384a0d871ad7cf97fd9ebbe Mon Sep 17 00:00:00 2001 From: Jason Grout Date: Thu, 25 Jun 2015 19:17:23 -0400 Subject: [PATCH] Rough draft of documentation for the notebook REST API for kernels, kernel specs, and sessions --- notebook/services/API.yaml | 365 +++++++++++++++++++++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100644 notebook/services/API.yaml diff --git a/notebook/services/API.yaml b/notebook/services/API.yaml new file mode 100644 index 000000000..1c8b7c9ec --- /dev/null +++ b/notebook/services/API.yaml @@ -0,0 +1,365 @@ +swagger: '2.0' +info: + title: Jupyter Notebook API + description: Notebook API + version: "4" + contact: + name: Jupyter Project + url: jupyter.org +# will be prefixed to all paths +basePath: /api +produces: + - application/json +consumes: + - application/json +parameters: + kernel: + name: kernel + required: true + in: path + description: kernel uuid + type: string + format: uuid + session: + name: session + required: true + in: path + description: session uuid + type: string + format: uuid + +paths: + /sessions/{session}: + parameters: + - $ref: '#/parameters/session' + get: + summary: Get session + tags: + - sessions + responses: + 200: + description: Session + schema: + $ref: '#/definitions/Session' + patch: + summary: This can be used to rename the notebook, or move it to a new directory. + tags: + - sessions + parameters: + - name: model + in: body + required: true + schema: + type: object + properties: + notebook: + type: object + properties: + path: + type: string + format: path + description: new path for notebook + responses: + 200: + description: Session + schema: + $ref: '#/definitions/Session' + 400: + description: No data provided + delete: + summary: Delete a session + tags: + - sessions + responses: + 204: + description: Session (and kernel) were deleted + 410: + description: Kernel was deleted before the session, and the session was *not* deleted (TODO - check to make sure session wasn't deleted) + /sessions: + get: + summary: List available sessions + tags: + - sessions + responses: + 200: + description: List of current sessions + schema: + type: array + items: + $ref: '#/definitions/Session' + post: + summary: Create a new session, or return an existing session if a session for the notebook path already exists + tags: + - sessions + parameters: + - name: session + in: body + schema: + type: object + properties: + notebook: + type: object + required: + - path + properties: + path: + type: string + description: path to notebook file + kernel: + type: object + properties: + name: + type: string + description: Kernel spec name, defaults to default kernel spec + responses: + 201: + description: Session created or returned + schema: + $ref: '#/definitions/Session' + headers: + Location: + description: URL for session commands + type: string + format: url + 501: + description: Kernel not available + schema: + type: object + description: error message + properties: + message: + type: string + short_message: + type: string + + /kernels: + get: + summary: List the JSON data for all kernels that are currently running + tags: + - kernels + responses: + 200: + description: List of currently-running kernel uuids + schema: + type: array + items: + $ref: '#/definitions/Kernel' + post: + summary: Start a kernel and return the uuid + tags: + - kernels + parameters: + - name: name + in: body + description: Kernel spec name (defaults to default kernel spec for server) + schema: + type: object + properties: + name: + type: string + responses: + 201: + description: Kernel started + headers: + Location: + description: URL for kernel commands + type: string + format: url + /kernels/{kernel}: + parameters: + - $ref: '#/parameters/kernel' + get: + summary: Get kernel information + tags: + - kernels + responses: + 200: + description: Kernel information + schema: + $ref: '#/definitions/Kernel' + delete: + summary: Kill a kernel and delete the kernel id + tags: + - kernels + responses: + 204: + description: Kernel deleted + /kernels/{kernel}/interrupt: + parameters: + - $ref: '#/parameters/kernel' + post: + summary: Interrupt a kernel + tags: + - kernels + responses: + 204: + description: Kernel interrupted + /kernels/{kernel}/restart: + parameters: + - $ref: '#/parameters/kernel' + post: + summary: Restart a kernel + tags: + - kernels + responses: + 200: + description: Kernel interrupted + headers: + Location: + description: URL for kernel commands + type: string + format: url + schema: + $ref: '#/definitions/Kernel' + + /kernelspecs: + get: + summary: List kernel specs + tags: + - kernelspecs + responses: + 200: + description: Kernel specs + schema: + type: object + properties: + default: + type: string + description: Default kernel name + kernelspecs: + type: array + items: + $ref: '#/definitions/KernelSpec' + /kernelspecs/{kernel}: + parameters: + - $ref: '#/parameters/kernel' + get: + summary: Kernel information + tags: + - kernelspecs + responses: + 200: + description: The contents of kernel.json + schema: + $ref: '#/definitions/KernelSpec' + 404: + description: Kernel spec not found + /kernelspecs/{kernel}/{filename}: + get: + summary: Retrieve a file from the kernel directory + tags: + - kernelspecs + parameters: + - name: kernel + in: path + description: Kernel uuid + type: string + required: true + - name: filename + in: path + description: filename + type: string + required: true + responses: + 200: + description: file + +definitions: + KernelSpec: + description: Kernel spec (contents of kernel.json) + properties: + name: + type: string + description: Unique name for kernel + spec: + $ref: '#/definitions/KernelSpecFile' + description: Kernel spec json file + resources: + type: object + properties: + kernel.js: + type: string + format: filename + description: path for kernel.js file + kernel.css: + type: string + format: filename + description: path for kernel.css file + logo-*: + type: string + format: filename + description: path for logo file. Logo filenames are of the form `logo-widthxheight` + KernelSpecFile: + description: Kernel spec json file + required: + - argv + - display_name + - language + properties: + language: + type: string + description: The programming language which this kernel runs. This will be stored in notebook metadata. + argv: + type: array + description: A list of command line arguments used to start the kernel. The text `{connection_file}` in any argument will be replaced with the path to the connection file. + items: + type: string + display_name: + type: string + description: The kernel's name as it should be displayed in the UI. Unlike the kernel name used in the API, this can contain arbitrary unicode characters. + codemirror_mode: + type: string + description: Codemirror mode. Can be a string *or* an valid Codemirror mode object. This defaults to the string from the `language` property. + env: + type: object + description: A dictionary of environment variables to set for the kernel. These will be added to the current environment variables. + additionalProperties: + type: string + help_links: + type: array + description: Help items to be displayed in the help menu in the notebook UI. + items: + type: object + required: + - text + - url + properties: + text: + type: string + description: menu item link text + url: + type: string + format: URL + description: menu item link url + Kernel: + description: Kernel information + required: + - id + - name + properties: + id: + type: string + format: uuid + description: uuid of kernel + name: + type: string + description: kernel spec name + Session: + description: A session + type: object + properties: + id: + type: string + format: uuid + notebook: + type: object + properties: + path: + type: string + description: path to notebook + kernel: + $ref: '#/definitions/Kernel' + + + +