mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-10 03:23:04 +00:00
2344d696ca
- This will allow, for example, cull_idle_servers to be more intelligent when culling servers. - This is only given to admin API users, because we don't know if all spawners expect their state to be made available to users.
720 lines
21 KiB
YAML
720 lines
21 KiB
YAML
# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default
|
|
swagger: '2.0'
|
|
info:
|
|
title: JupyterHub
|
|
description: The REST API for JupyterHub
|
|
version: 0.9.0dev
|
|
license:
|
|
name: BSD-3-Clause
|
|
schemes:
|
|
- [http, https]
|
|
securityDefinitions:
|
|
token:
|
|
type: apiKey
|
|
name: Authorization
|
|
in: header
|
|
security:
|
|
- token: []
|
|
basePath: /hub/api
|
|
produces:
|
|
- application/json
|
|
consumes:
|
|
- application/json
|
|
paths:
|
|
/:
|
|
get:
|
|
summary: Get JupyterHub version
|
|
description: |
|
|
This endpoint is not authenticated for the purpose of clients and user
|
|
to identify the JupyterHub version before setting up authentication.
|
|
responses:
|
|
'200':
|
|
description: The JupyterHub version
|
|
schema:
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: The version of JupyterHub itself
|
|
/info:
|
|
get:
|
|
summary: Get detailed info about JupyterHub
|
|
description: |
|
|
Detailed JupyterHub information, including Python version,
|
|
JupyterHub's version and executable path,
|
|
and which Authenticator and Spawner are active.
|
|
responses:
|
|
'200':
|
|
description: Detailed JupyterHub info
|
|
schema:
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: The version of JupyterHub itself
|
|
python:
|
|
type: string
|
|
description: The Python version, as returned by sys.version
|
|
sys_executable:
|
|
type: string
|
|
description: The path to sys.executable running JupyterHub
|
|
authenticator:
|
|
type: object
|
|
properties:
|
|
class:
|
|
type: string
|
|
description: The Python class currently active for JupyterHub Authentication
|
|
version:
|
|
type: string
|
|
description: The version of the currently active Authenticator
|
|
spawner:
|
|
type: object
|
|
properties:
|
|
class:
|
|
type: string
|
|
description: The Python class currently active for spawning single-user notebook servers
|
|
version:
|
|
type: string
|
|
description: The version of the currently active Spawner
|
|
/users:
|
|
get:
|
|
summary: List users
|
|
responses:
|
|
'200':
|
|
description: The Hub's user list
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/User'
|
|
post:
|
|
summary: Create multiple users
|
|
parameters:
|
|
- name: data
|
|
in: body
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
usernames:
|
|
type: array
|
|
description: list of usernames to create on the Hub
|
|
items:
|
|
type: string
|
|
admin:
|
|
description: whether the created users should be admins
|
|
type: boolean
|
|
responses:
|
|
'201':
|
|
description: The users have been created
|
|
schema:
|
|
type: array
|
|
description: The created users
|
|
items:
|
|
$ref: '#/definitions/User'
|
|
/users/{name}:
|
|
get:
|
|
summary: Get a user by name
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The User model
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
post:
|
|
summary: Create a single user
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'201':
|
|
description: The user has been created
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
patch:
|
|
summary: Modify a user
|
|
description: Change a user's name or admin status
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
- name: data
|
|
in: body
|
|
required: true
|
|
description: Updated user info. At least one key to be updated (name or admin) is required.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: the new name (optional, if another key is updated i.e. admin)
|
|
admin:
|
|
type: boolean
|
|
description: update admin (optional, if another key is updated i.e. name)
|
|
responses:
|
|
'200':
|
|
description: The updated user info
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
delete:
|
|
summary: Delete a user
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'204':
|
|
description: The user has been deleted
|
|
/users/{name}/server:
|
|
post:
|
|
summary: Start a user's single-user notebook server
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'201':
|
|
description: The user's notebook server has started
|
|
'202':
|
|
description: The user's notebook server has not yet started, but has been requested
|
|
delete:
|
|
summary: Stop a user's server
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'204':
|
|
description: The user's notebook server has stopped
|
|
'202':
|
|
description: The user's notebook server has not yet stopped as it is taking a while to stop
|
|
/users/{name}/servers/{server_name}:
|
|
post:
|
|
summary: Start a user's single-user named-server notebook server
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
- name: server_name
|
|
description: name given to a named-server
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'201':
|
|
description: The user's notebook named-server has started
|
|
'202':
|
|
description: The user's notebook named-server has not yet started, but has been requested
|
|
delete:
|
|
summary: Stop a user's named-server
|
|
parameters:
|
|
- name: name
|
|
description: username
|
|
in: path
|
|
required: true
|
|
type: string
|
|
- name: server_name
|
|
description: name given to a named-server
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'204':
|
|
description: The user's notebook named-server has stopped
|
|
'202':
|
|
description: The user's notebook named-server has not yet stopped as it is taking a while to stop
|
|
/users/{name}/tokens:
|
|
get:
|
|
summary: List tokens for the user
|
|
responses:
|
|
'200':
|
|
description: The list of tokens
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Token'
|
|
post:
|
|
summary: Create a new token for the user
|
|
responses:
|
|
'201':
|
|
description: The newly created token
|
|
schema:
|
|
$ref: '#/definitions/Token'
|
|
/users/{name}/tokens/{token_id}:
|
|
get:
|
|
summary: Get the model for a token by id
|
|
responses:
|
|
'200':
|
|
description: The info for the new token
|
|
schema:
|
|
$ref: '#/definitions/Token'
|
|
delete:
|
|
summary: Delete (revoke) a token by id
|
|
responses:
|
|
'204':
|
|
description: The token has been deleted
|
|
/user:
|
|
summary: Return authenticated user's model
|
|
description:
|
|
parameters:
|
|
responses:
|
|
'200':
|
|
description: The authenticated user's model is returned.
|
|
/groups:
|
|
get:
|
|
summary: List groups
|
|
responses:
|
|
'200':
|
|
description: The list of groups
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Group'
|
|
/groups/{name}:
|
|
get:
|
|
summary: Get a group by name
|
|
parameters:
|
|
- name: name
|
|
description: group name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The group model
|
|
schema:
|
|
$ref: '#/definitions/Group'
|
|
post:
|
|
summary: Create a group
|
|
parameters:
|
|
- name: name
|
|
description: group name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'201':
|
|
description: The group has been created
|
|
schema:
|
|
$ref: '#/definitions/Group'
|
|
delete:
|
|
summary: Delete a group
|
|
parameters:
|
|
- name: name
|
|
description: group name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'204':
|
|
description: The group has been deleted
|
|
/groups/{name}/users:
|
|
post:
|
|
summary: Add users to a group
|
|
parameters:
|
|
- name: name
|
|
description: group name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
- name: data
|
|
in: body
|
|
required: true
|
|
description: The users to add to the group
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
description: List of usernames to add to the group
|
|
items:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The users have been added to the group
|
|
schema:
|
|
$ref: '#/definitions/Group'
|
|
delete:
|
|
summary: Remove users from a group
|
|
parameters:
|
|
- name: name
|
|
description: group name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
- name: data
|
|
in: body
|
|
required: true
|
|
description: The users to remove from the group
|
|
schema:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
description: List of usernames to remove from the group
|
|
items:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The users have been removed from the group
|
|
/services:
|
|
get:
|
|
summary: List services
|
|
responses:
|
|
'200':
|
|
description: The service list
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Service'
|
|
/services/{name}:
|
|
get:
|
|
summary: Get a service by name
|
|
parameters:
|
|
- name: name
|
|
description: service name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The Service model
|
|
schema:
|
|
$ref: '#/definitions/Service'
|
|
/proxy:
|
|
get:
|
|
summary: Get the proxy's routing table
|
|
description: A convenience alias for getting the routing table directly from the proxy
|
|
responses:
|
|
'200':
|
|
description: Routing table
|
|
schema:
|
|
type: object
|
|
description: configurable-http-proxy routing table (see configurable-http-proxy docs for details)
|
|
post:
|
|
summary: Force the Hub to sync with the proxy
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
patch:
|
|
summary: Notify the Hub about a new proxy
|
|
description: Notifies the Hub of a new proxy to use.
|
|
parameters:
|
|
- name: data
|
|
in: body
|
|
required: true
|
|
description: Any values that have changed for the new proxy. All keys are optional.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
ip:
|
|
type: string
|
|
description: IP address of the new proxy
|
|
port:
|
|
type: string
|
|
description: Port of the new proxy
|
|
protocol:
|
|
type: string
|
|
description: Protocol of new proxy, if changed
|
|
auth_token:
|
|
type: string
|
|
description: CONFIGPROXY_AUTH_TOKEN for the new proxy
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
/authorizations/token:
|
|
post:
|
|
summary: Request a new API token
|
|
description: |
|
|
Request a new API token to use with the JupyterHub REST API.
|
|
If not already authenticated, username and password can be sent
|
|
in the JSON request body.
|
|
Logging in via this method is only available when the active Authenticator
|
|
accepts passwords (e.g. not OAuth).
|
|
parameters:
|
|
- name: username
|
|
in: body
|
|
required: false
|
|
type: string
|
|
- name: password
|
|
in: body
|
|
required: false
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The new API token
|
|
schema:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: The new API token.
|
|
'403':
|
|
description: The user can not be authenticated.
|
|
/authorizations/token/{token}:
|
|
get:
|
|
summary: Identify a user or service from an API token
|
|
parameters:
|
|
- name: token
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The user or service identified by the API token
|
|
'404':
|
|
description: A user or service is not found.
|
|
/authorizations/cookie/{cookie_name}/{cookie_value}:
|
|
get:
|
|
summary: Identify a user from a cookie
|
|
description: Used by single-user notebook servers to hand off cookie authentication to the Hub
|
|
parameters:
|
|
- name: cookie_name
|
|
in: path
|
|
required: true
|
|
type: string
|
|
- name: cookie_value
|
|
in: path
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: The user identified by the cookie
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
'404':
|
|
description: A user is not found.
|
|
/oauth2/authorize:
|
|
get:
|
|
summary: 'OAuth 2.0 authorize endpoint'
|
|
description: |
|
|
Redirect users to this URL to begin the OAuth process.
|
|
It is not an API endpoint.
|
|
parameters:
|
|
- name: client_id
|
|
description: The client id
|
|
in: query
|
|
required: true
|
|
type: string
|
|
- name: response_type
|
|
description: The response type (always 'code')
|
|
in: query
|
|
required: true
|
|
type: string
|
|
- name: state
|
|
description: A state string
|
|
in: query
|
|
required: false
|
|
type: string
|
|
- name: redirect_uri
|
|
description: The redirect url
|
|
in: query
|
|
required: true
|
|
type: string
|
|
/oauth2/token:
|
|
post:
|
|
summary: Request an OAuth2 token
|
|
description: |
|
|
Request an OAuth2 token from an authorization code.
|
|
This request completes the OAuth process.
|
|
consumes:
|
|
- application/x-www-form-urlencoded
|
|
parameters:
|
|
- name: client_id
|
|
description: The client id
|
|
in: form
|
|
required: true
|
|
type: string
|
|
- name: client_secret
|
|
description: The client secret
|
|
in: form
|
|
required: true
|
|
type: string
|
|
- name: grant_type
|
|
description: The grant type (always 'authorization_code')
|
|
in: form
|
|
required: true
|
|
type: string
|
|
- name: code
|
|
description: The code provided by the authorization redirect
|
|
in: form
|
|
required: true
|
|
type: string
|
|
- name: redirect_uri
|
|
description: The redirect url
|
|
in: form
|
|
required: true
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: JSON response including the token
|
|
schema:
|
|
type: object
|
|
properties:
|
|
access_token:
|
|
type: string
|
|
description: The new API token for the user
|
|
token_type:
|
|
type: string
|
|
description: Will always be 'Bearer'
|
|
/shutdown:
|
|
post:
|
|
summary: Shutdown the Hub
|
|
parameters:
|
|
- name: proxy
|
|
in: body
|
|
type: boolean
|
|
description: Whether the proxy should be shutdown as well (default from Hub config)
|
|
- name: servers
|
|
in: body
|
|
type: boolean
|
|
description: Whether users' notebook servers should be shutdown as well (default from Hub config)
|
|
definitions:
|
|
User:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The user's name
|
|
admin:
|
|
type: boolean
|
|
description: Whether the user is an admin
|
|
groups:
|
|
type: array
|
|
description: The names of groups where this user is a member
|
|
items:
|
|
type: string
|
|
server:
|
|
type: string
|
|
description: The user's notebook server's base URL, if running; null if not.
|
|
pending:
|
|
type: string
|
|
enum: ["spawn", "stop", null]
|
|
description: The currently pending action, if any
|
|
last_activity:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of last-seen activity from the user
|
|
servers:
|
|
type: object
|
|
description: The active servers for this user.
|
|
items:
|
|
schema:
|
|
$ref: '#/definitions/Server'
|
|
Server:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The server's name. The user's default server has an empty name ('')
|
|
ready:
|
|
type: boolean
|
|
description: |
|
|
Whether the server is ready for traffic.
|
|
Will always be false when any transition is pending.
|
|
pending:
|
|
type: string
|
|
enum: ["spawn", "stop", null]
|
|
description: |
|
|
The currently pending action, if any.
|
|
A server is not ready if an action is pending.
|
|
url:
|
|
type: string
|
|
description: |
|
|
The URL where the server can be accessed
|
|
(typically /user/:name/:server.name/).
|
|
progress_url:
|
|
type: string
|
|
description: |
|
|
The URL for an event-stream to retrieve events during a spawn.
|
|
started:
|
|
type: string
|
|
format: date-time
|
|
description: UTC timestamp when the server was last started.
|
|
last_activity:
|
|
type: string
|
|
format: date-time
|
|
description: UTC timestamp last-seen activity on this server.
|
|
state:
|
|
type: object
|
|
description: Arbitrary internal state from this server's spawner. Only available on the hub's users list or get-user-by-name method, and only if a hub admin. None otherwise.
|
|
Group:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The group's name
|
|
users:
|
|
type: array
|
|
description: The names of users who are members of this group
|
|
items:
|
|
type: string
|
|
Service:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The service's name
|
|
admin:
|
|
type: boolean
|
|
description: Whether the service is an admin
|
|
url:
|
|
type: string
|
|
description: The internal url where the service is running
|
|
prefix:
|
|
type: string
|
|
description: The proxied URL prefix to the service's url
|
|
pid:
|
|
type: number
|
|
description: The PID of the service process (if managed)
|
|
command:
|
|
type: array
|
|
description: The command used to start the service (if managed)
|
|
items:
|
|
type: string
|
|
Token:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: The token itself. Only present in responses to requests for a new token.
|
|
id:
|
|
type: string
|
|
description: The id of the API token. Used for modifying or deleting the token.
|
|
user:
|
|
type: string
|
|
description: The user that owns a token (undefined if owned by a service)
|
|
service:
|
|
type: string
|
|
description: The service that owns the token (undefined of owned by a user)
|
|
note:
|
|
type: string
|
|
description: A note about the token, typically describing what it was created for.
|
|
created:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when this token was created
|
|
last_activity:
|
|
type: string
|
|
format: date-time
|
|
description: |
|
|
Timestamp of last-seen activity using this token.
|
|
Can be null if token has never been used.
|