Merge pull request #173 from jasongrout/swagger
Rough draft of documentation for the notebook REST API for kernels, kernel specs, and sessionspull/213/head
Min RK
11 years ago
commit
71c2387e34
@ -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'
|
||||
|
||||
|
||||
|
||||
|
||||
@ -0,0 +1,22 @@
|
||||
"""Tornado handlers for api specifications."""
|
||||
|
||||
# Copyright (c) Jupyter Development Team.
|
||||
# Distributed under the terms of the Modified BSD License.
|
||||
|
||||
from tornado import web
|
||||
from ...base.handlers import IPythonHandler
|
||||
import os
|
||||
|
||||
class APIHandler(web.StaticFileHandler, IPythonHandler):
|
||||
|
||||
def initialize(self):
|
||||
web.StaticFileHandler.initialize(self, path=os.path.dirname(__file__))
|
||||
|
||||
@web.authenticated
|
||||
def get(self):
|
||||
self.log.debug("Serving api")
|
||||
return web.StaticFileHandler.get(self, 'api.yaml')
|
||||
|
||||
default_handlers = [
|
||||
(r"/api", APIHandler)
|
||||
]
|
||||
Loading…
Reference in new issue