jupyterhub/docs/rest-api.yml

# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default
swagger: '2.0'
info:
  title: JupyterHub
  description: The REST API for JupyterHub
  version: 1.2.0dev
  license:
    name: BSD-3-Clause
schemes:
  [http, https]
securityDefinitions:
  token:
    type: apiKey
    name: Authorization
    in: header
  oauth2:
    type: oauth2
    flow: accessCode
    authorizationUrl: '/hub/api/oauth2/authorize' # what are the absolute URIs here? is oauth2 correct here or shall we use just authorizations?
    tokenUrl: '/hub/api/oauth2/token'
    scopes:
      all: Everything a user can do
      read:all: Read-only access to everything a user can read (also whoami handler)
      users: Grants access to managing users including reading users’ model, posting activity and starting/stoping users servers
      read:users: Read-only access to the above
      read:users!user=username: Read-only access to a single user's model
      read:users:names: Read-only access to users' names
      read:users:groups: Read-only access to users' groups
      read:users:activity: Read-only access to users' activity
      read:users:activity!group=groupname: Read-only access to specific group's users' activity
      read:users:servers: Read-only access to users' servers
      users:activity!user=username: Update a user's activity
      users:servers: Grants access to start/stop any server
      users:servers!server=servername: Limits the above to a specific server
      users:tokens: Grants access to users' token (includes create/revoke a token)
      read:users:tokens: Identify a user from a token
      admin:users: Grants access to creating/removing users
      admin:users:servers: Grants access to create/remove users' servers
      groups: Add/remove users from any group
      groups!group=groupname: Add/remove users from a specific group only
      read:groups: Read-only access to groups
      admin:groups: Grants access to create/delete groups
      read:services: Read-only access to services
      proxy: Grants access to proxy's routing table, syncing and notifying about a new proxy
      shutdown: Grants access to shutdown the Hub
security: # global security, do we want to keep only the apiKey (token: []), change to only oauth2 (with scope all) or have both (either can be used)?
  - token: []
  - oauth2:
    - all
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
      security:
        - oauth2:
          - users
          - read:users
      responses:
        '200':
          description: The Hub's user list
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    post:
      summary: Create multiple users
      security:
        - oauth2:
          - admin:users
      parameters:
        - name: body
          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
      security:
        - oauth2:
          - users
          - read:users
          - read:users!user=username
      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
      security:
        - oauth2:
          - admin:users
      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
      security:
        - oauth2:
          - users
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: body
          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
      security:
        - oauth2:
          - admin:users
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The user has been deleted
  /users/{name}/activity:
    post:
      summary:
        Notify Hub of activity for a given user.
      description:
        Notify the Hub of activity by the user,
        e.g. accessing a service or (more likely)
        actively using a server.
      security:
        - oauth2:
          - users
          - users:activity!user=username
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: body
          in: body
          schema:
            type: object
            properties:
              last_activity:
                type: string
                format: date-time
                description: |
                  Timestamp of last-seen activity for this user.
                  Only needed if this is not activity associated
                  with using a given server.
              servers:
                description: |
                  Register activity for specific servers by name.
                  The keys of this dict are the names of servers.
                  The default server has an empty name ('').
                type: object
                properties:
                  '<server name>':
                    description: |
                      Activity for a single server.
                    type: object
                    required:
                      - last_activity
                    properties:
                      last_activity:
                        type: string
                        format: date-time
                        description: |
                          Timestamp of last-seen activity on this server.
            example:
              last_activity: '2019-02-06T12:54:14Z'
              servers:
                '':
                  last_activity: '2019-02-06T12:54:14Z'
                gpu:
                  last_activity: '2019-02-06T12:54:14Z'
      responses:
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          description: No such user
  /users/{name}/server:
    post:
      summary: Start a user's single-user notebook server
      security:
        - oauth2:
          - users
          - users:servers
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: options
          description: |
            Spawn options can be passed as a JSON body
            when spawning via the API instead of spawn form.
            The structure of the options
            will depend on the Spawner's configuration.
            The body itself will be available as `user_options` for the
            Spawner.
          in: body
          required: false
          schema:
            type: object

      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
      security:
        - oauth2:
          - users
          - users:servers
      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
      security:
        - oauth2:
          - users
          - users:servers
          - users:servers!server=servername
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: server_name
          description: |
            name given to a named-server. 
            
            Note that depending on your JupyterHub infrastructure there are chracterter size limitation to `server_name`. Default spawner with K8s pod will not allow Jupyter Notebooks to be spawned with a name that contains more than 253 characters (keep in mind that the pod will be spawned with extra characters to identify the user and hub).
          in: path
          required: true
          type: string
        - name: options
          description: |
            Spawn options can be passed as a JSON body
            when spawning via the API instead of spawn form.
            The structure of the options
            will depend on the Spawner's configuration.
          in: body
          required: false
          schema:
            type: object
      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
      security:
        - oauth2:
          - users
          - users:servers
          - users:servers!server=servername
      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
        - name: body
          in: body
          required: false
          schema:
            type: object
            properties:
              remove:
                type: boolean
                description: |
                  Whether to fully remove the server, rather than just stop it.
                  Removing a server deletes things like the state of the stopped server.
                  Default: false.
      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:
    parameters:
      - name: name
        description: username
        in: path
        required: true
        type: string
    get:
      summary: List tokens for the user
      security:
        - oauth2:
          - users:tokens
      responses:
        '200':
          description: The list of tokens
          schema:
            type: array
            items:
              $ref: '#/definitions/Token'
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          description: No such user
    post:
      summary: Create a new token for the user
      security:
        - oauth2:
          - users:tokens
      parameters:
        - name: token_params
          in: body
          required: false
          schema:
            type: object
            properties:
              expires_in:
                type: number
                description: lifetime (in seconds) after which the requested token will expire.
              note:
                type: string
                description: A note attached to the token for future bookkeeping
              roles:
                type: list
                description: A list of role names that the token should have
      responses:
        '201':
          description: The newly created token
          schema:
            $ref: '#/definitions/Token'
        '400':
          description: Body must be a JSON dict or empty
        '403':
          description: Requested role does not exist
  /users/{name}/tokens/{token_id}:
    parameters:
      - name: name
        description: username
        in: path
        required: true
        type: string
      - name: token_id
        in: path
        required: true
        type: string
    get:
      summary: Get the model for a token by id
      security:
        - oauth2:
          - users:tokens
      responses:
        '200':
          description: The info for the new token
          schema:
            $ref: '#/definitions/Token'
    delete:
      summary: Delete (revoke) a token by id
      security:
        - oauth2:
          - users:tokens
      responses:
        '204':
          description: The token has been deleted
  /user:
    get:
      summary: Return authenticated user's model
      security:
        - oauth2:
          - all
          - read:all
      responses:
        '200':
          description: The authenticated user's model is returned.
          schema:
            $ref: '#/definitions/User'
  /groups:
    get:
      summary: List groups
      security:
        - oauth2:
          - groups
          - read:groups
      responses:
        '200':
          description: The list of groups
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
  /groups/{name}:
    get:
      summary: Get a group by name
      security:
        - oauth2:
          - groups
          - groups!group=groupname
          - read:groups
      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
      security:
        - oauth2:
          - admin:groups
      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
      security:
        - oauth2:
          - admin:groups
      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
      security:
        - oauth2:
          - groups
          - groups!group=groupname
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
        - name: body
          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
      security:
        - oauth2:
          - groups
          - groups!group=groupname
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
        - name: body
          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
      security:
        - oauth2:
          - read:services
      responses:
        '200':
          description: The service list
          schema:
            type: array
            items:
              $ref: '#/definitions/Service'
  /services/{name}:
    get:
      summary: Get a service by name
      security:
        - oauth2:
          - read:services
      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
      security:
        - oauth2:
          - 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
      security:
        - oauth2:
          - proxy
      responses:
        '200':
          description: Success
    patch:
      summary: Notify the Hub about a new proxy
      description: Notifies the Hub of a new proxy to use.
      security:
        - oauth2:
          - proxy
      parameters:
        - name: body
          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).
      security:
        - oauth2:
          - users:tokens # minrk: this is a deprecated alias to POST /users/{name}/tokens, either remove it or use the same scope
      parameters:
        - name: credentials
          in: body
          schema:
            type: object
            properties:
              username:
                type: string
              password:
                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
      security:
        - oauth2:
          - read:users:tokens # minrk: is it really necessary to have a scope for this, or use self handler for token whoami?
      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.
      deprecated: true # minrk: let’s not add a scope for this, let’s remove it
  /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
      responses:
        '200':
          description: Success
        '400':
          description: OAuth2Error
  /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: formData
          required: true
          type: string
        - name: client_secret
          description: The client secret
          in: formData
          required: true
          type: string
        - name: grant_type
          description: The grant type (always 'authorization_code')
          in: formData
          required: true
          type: string
        - name: code
          description: The code provided by the authorization redirect
          in: formData
          required: true
          type: string
        - name: redirect_uri
          description: The redirect url
          in: formData
          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
      security:
        - oauth2:
          - shutdown
      parameters:
        - name: body
          in: body
          schema:
            type: object
            properties:
              proxy:
                type: boolean
                description: Whether the proxy should be shutdown as well (default from Hub config)
              servers:
                type: boolean
                description: Whether users' notebook servers should be shutdown as well (default from Hub config)
      responses:
        '202':
          description: Shutdown successful
        '400':
          description: Unexpeced value for proxy or servers
# Descriptions of common responses
responses:
  NotFound:
    description: The specified resource was not found
  Unauthorized:
    description: Authentication/Authorization error
definitions:
  User:
    type: object
    properties:
      name:
        type: string
        description: The user's name
      admin:
        type: boolean
        description: Whether the user is an admin
      roles:
        type: array
        description: The names of roles this user has
        items:
          type: string
      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: array
        description: The active servers for this user.
        items:
          $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.
      user_options:
        type: object
        description: User specified options for the user's spawned instance of a single-user server.
  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
      roles:
        type: array
        description: The names of roles this service has
        items:
          type: string
      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
      info:
        type: object
        description: |
          Additional information a deployment can attach to a service.
          JupyterHub does not use this field.
  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)
      roles:
        type: array
        description: The names of roles this token has
        items:
          type: string
      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
      expires_at:
        type: string
        format: date-time
        description: Timestamp when this token expires. Null if there is no expiry.
      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.