Canonical Session API

openapi: 3.2.0
info:
  description: The Anbox Stream Gateway provides federated access to Anbox Cloud regions.
  title: Anbox Stream Gateway Session API
  contact:
    name: Canonical
    url: https://ubuntu.com/support
    email: indore@lists.canonical.com
  license:
    name: Proprietary
  version: '1.0'
servers:
- url: /1.0/
tags:
- name: Session
paths:
  /1.0/session/{id}/sockets/adb:
    get:
      description: 'A websocket connection endpoint which initiates the signaling process with the adb role.

        This URL is returned then joining a session along with its credentials.'
      tags:
      - Session
      summary: Join session as ADB client
      operationId: handle-adb-connect-session
      responses: {}
  /1.0/session/{id}/sockets/master:
    get:
      description: 'A websocket connection endpoint which initiates the signaling process with the master role.

        You MUST call /sessions/{id}/join beforehand to prepare the android container.'
      tags:
      - Session
      summary: Join session as master
      operationId: handle-master-connect-session
      responses: {}
  /1.0/session/{id}/sockets/slave:
    get:
      description: 'A websocket connection endpoint which initiates the signaling process with the slave role.

        This URL is returned then joining a session along with its credentials.'
      tags:
      - Session
      summary: Join session as slave
      operationId: handle-slave-connect-session
      responses: {}
  /1.0/sessions:
    get:
      security:
      - AuthToken: []
      tags:
      - Session
      summary: Get all sessions
      operationId: handle-get-sessions
      parameters:
      - description: Filter returned sessions by given status
        name: status
        in: query
        schema:
          type: string
      - description: Return full session objects rather than just their ID
        name: recursive
        in: query
        schema:
          type: boolean
      - description: Limit number of results returned
        name: limit
        in: query
        schema:
          type: integer
      - description: Offset to list results from
        name: offset
        in: query
        schema:
          type: integer
      - description: Field of the session to sort results by
        name: sort_by
        in: query
        schema:
          type: string
      - description: 'Sort order of the returned results. Possible values are: asc, desc'
        name: sort_order
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionsGetResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
    post:
      security:
      - AuthToken: []
      description: 'Create a new session based on an application, application version, region

        and screen details. The newly created session is started immediately after

        being created. The returned session details can be used to immediately start

        the signaling process. If an application version is not specified, the latest

        application version will always be in use for a session creation.'
      tags:
      - Session
      summary: Create session
      operationId: handle-new-session
      responses:
        '201':
          description: Newly created session along with the information needed to connect to it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionPostResponse'
        '400':
          description: Invalid body or missing application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '404':
          description: No agent can host the container
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.SessionPost'
        description: Session details
        required: true
    delete:
      security:
      - AuthToken: []
      tags:
      - Session
      summary: Batch delete sessions
      operationId: handle-delete-sessions
      parameters:
      - description: Force deletion even if agent is not available. This may leave a container around on the agent.
        name: force
        in: query
        schema:
          type: boolean
      - description: Set to true to wait for the response (can take a long time for lots of sessions) or to false to return without waiting for all sessions to be deleted. Defaults to false
        name: sync
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Contains an array of deleted sessions as well as potential errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionsDeleteResponse'
        '202':
          description: Returned when sync=true. Watch the session list for progress on the operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '207':
          description: Some sessions could not be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '404':
          description: Non-existent sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '500':
          description: Internal issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.SessionsDelete'
        description: List of session IDs to delete
        required: true
  /1.0/sessions/{id}:
    get:
      security:
      - AuthToken: []
      description: Returns a session from its ID.
      tags:
      - Session
      summary: Get session
      operationId: handle-get-session
      parameters:
      - description: Session ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionGetResponse'
        '400':
          description: Invalid session ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '404':
          description: Non-existent session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
    delete:
      security:
      - AuthToken: []
      tags:
      - Session
      summary: Delete a session
      operationId: handle-delete-session
      parameters:
      - description: Session ID
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Force deletion even if agent is not available. This may leave a container around on the agent.
        name: force
        in: query
        schema:
          type: boolean
      - description: Set to true to wait for the response or to false to return early without waiting for the session to be deleted
        name: sync
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Empty response to indicate success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '400':
          description: Invalid session ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '404':
          description: Non-existent session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
  /1.0/sessions/{id}/connect:
    get:
      description: 'Connect an existing running session from a client. The returned

        object contains a URL with the required credentials for a client

        to connect to the remote Anbox instance.'
      tags:
      - Session
      summary: Connect a session
      operationId: handle-connect-session
      responses:
        '200':
          description: Object containing a URL with the required credentials to connect to the remote Anbox instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionConnectGetResponse'
        '400':
          description: Missing session ID, inactive session, invalid connection type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '401':
          description: Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '500':
          description: Error when failing to generate auth token/STUN servers, or setup connection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
  /1.0/sessions/{id}/join:
    post:
      security:
      - AuthToken: []
      description: 'Join an existing running session. The session must already be running. The

        returned object contains a URL with the required credentials for a client

        to join the signaling process.'
      tags:
      - Session
      summary: Join session
      operationId: handle-join-session
      responses:
        '200':
          description: Object containing the slave URL as well as optional additional STUN/TURN servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionJoinResponse'
        '400':
          description: Missing session ID or invalid session state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '404':
          description: The session does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '500':
          description: Error when trying to generate session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.SessionJoinPost'
        description: Additional information about the join request
        required: true
  /1.0/sessions/{id}/share:
    post:
      security:
      - AuthToken: []
      description: 'Share an existing running session with a client. The returned

        object contains a URL for a client to interact with a session'
      tags:
      - Session
      summary: Share session
      operationId: handle-share-session
      responses:
        '200':
          description: Object containing a URL for a client to interact with a session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api.SessionSharePostResponse'
        '400':
          description: Missing session ID, invalid request content, share type or expiration time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '404':
          description: The session does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
        '500':
          description: Error when failing to generate auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api_gateway.Response'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/api.SessionSharePost'
        description: Required parameters to the share request
        required: true
components:
  schemas:
    api_gateway.StunServer:
      type: object
      properties:
        password:
          description: 'Password is the optional password to authenticate on the STUN/TURN server.

            It is usually unique to a session.'
          type: string
          example: 3f14bdb1ecd3
        urls:
          description: URLs is the list of endpoints the STUN/TURN server can be reached on.
          type: array
          items:
            type: string
          example:
          - https://stun.foo.com
          - https://turn.foo.com
        username:
          description: 'Username is the optional username to authenticate on the STUN/TURN server.

            It is usually unique to a session.'
          type: string
          example: f3e3bcead096461d8
    api_gateway.ResponseStatus:
      type: string
      enum:
      - success
      - failed
      - unknown
      x-enum-varnames:
      - ResponseStatusSuccess
      - ResponseStatusFailed
      - ResponseStatusUnknown
    api.SessionsGetResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          type: array
          items:
            type: string
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        total_size:
          description: TotalSize specifies how many session objects are available in total
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api.Screen:
      type: object
      properties:
        density:
          description: 'Display density Android will be configured with. See https://developer.android.com/training/multiscreen/screendensities

            for more details'
          type: integer
          default: 240
          minimum: 72
          example: 240
        fps:
          description: FPS the video stream will use
          type: integer
          minimum: 1
          example: 25
        height:
          description: Height of the screen
          type: integer
          minimum: 1
          example: 720
        width:
          description: Width of the screen
          type: integer
          minimum: 1
          example: 1280
    api.SessionSharePostResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          description: Metadata contains a URL that a client can connect to interact with a session
          allOf:
          - $ref: '#/components/schemas/api.SessionSharePostResponseData'
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api.Session:
      type: object
      properties:
        app:
          description: 'App that will be run in the session.

            Applications are listed from AMS if they have been configured for streaming.'
          type: string
        cluster_id:
          description: ID of the cluster which the instance is deployed to
          type: string
          example: cluster0
        container_id:
          description: 'ID of the container powering the session. If no container was created yet

            or the container is destroyed, the ID will be empty.'
          type: string
          example: c05h1jj3pn6a8q46taug
        id:
          description: ID of the session.
          type: string
          example: e25f3e3bcead096461d89d8ab7043f14bdb1ecd39
        joinable:
          description: Marks wether the session is joinable or not
          type: boolean
        region:
          description: Region on which the instance is located.
          type: string
          example: eu-west-1
        status:
          description: "Status of the session.\n created: sent creation request to an available agent.\n active: container is up and running.\n error: an error occurred and the container is stopped.\n terminated: the container has stopped gracefully, either by manual command or timeout."
          enum:
          - created
          - active
          - error
          - terminating
          - terminated
          allOf:
          - $ref: '#/components/schemas/api.SessionStatus'
        status_message:
          description: Message giving more information about the current status
          type: string
          example: Container failed to start
    api.SessionPostResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          $ref: '#/components/schemas/api.SessionPostResponseData'
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api.SessionPostResponseData:
      type: object
      properties:
        id:
          description: ID of the session.
          type: string
          example: e25f3e3bcead096461d89d8ab7043f14bdb1ecd39
        joinable:
          description: Marks the session joinable after the initial client left
          type: boolean
          example: true
        region:
          description: 'Region is a cloud region where the application will be launched.

            Regions are registered dynamically by agents.'
          type: string
          example: eu-west-2
        status:
          description: "Status of the session.\n created: sent creation request to an available agent.\n active: container is up and running.\n error: an error occurred and the container is stopped.\n terminated: the container has stopped gracefully, either by manual command or timeout."
          enum:
          - created
          - active
          - error
          - terminating
          - terminated
          allOf:
          - $ref: '#/components/schemas/api.SessionStatus'
          example: active
        stun_servers:
          description: 'StunServers is a list of STUN servers with their optional credentials.

            They are passed to the client to figure out the best route to the

            actual android instance.

            They are used within the WebRTC protocol to negotiation a peer to peer transport

            between the Android instance and the connecting client.'
          type: array
          items:
            $ref: '#/components/schemas/api_gateway.StunServer'
        url:
          description: URL is the endpoint to reach to start the WebRTC signaling process.
          type: string
    api.SessionSharePostResponseData:
      type: object
      properties:
        expiry_min:
          description: The expiration time in minutes for the share URL
          type: integer
          example: 5
        url:
          description: URL is the endpoint to reach to start the WebRTC signaling process.
          type: string
          example: https://api.example.com/1.0/session/e25fcd39/connect?type=adb&token=foobar
    api.SessionStatus:
      type: string
      enum:
      - created
      - active
      - error
      - terminating
      - terminated
      x-enum-varnames:
      - SessionStatusCreated
      - SessionStatusActive
      - SessionStatusError
      - SessionStatusTerminating
      - SessionStatusTerminated
    api.SessionConnectGetResponseData:
      type: object
      properties:
        stun_servers:
          description: 'StunServers is a list of STUN servers with their optional credentials.

            They are passed to the client to figure out the best route to the

            actual android instance.

            They are used within the WebRTC protocol to negotiation a peer to peer transport

            between the Anbox instance and the connecting client.'
          type: array
          items:
            $ref: '#/components/schemas/api_gateway.StunServer'
        url:
          description: URL is the endpoint to reach to start the WebRTC signaling process.
          type: string
          example: wss://api.example.com/1.0/session/e25fcd39/sockets/adb?token=foobar
    api.SessionJoinResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          $ref: '#/components/schemas/api.SessionJoinResponseData'
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api_gateway.Response:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api.SessionJoinResponseData:
      type: object
      properties:
        stun_servers:
          description: 'StunServers is a list of STUN servers with their optional credentials.

            They are passed to the client to figure out the best route to the

            actual android instance.

            They are used within the WebRTC protocol to negotiation a peer to peer transport

            between the Android instance and the connecting client.'
          type: array
          items:
            $ref: '#/components/schemas/api_gateway.StunServer'
        url:
          description: URL is the endpoint to reach to start the WebRTC signaling process.
          type: string
          example: https://api.example.com/1.0/session/e25fcd39/sockets/slave?token=foobar
    api.SessionPost:
      type: object
      properties:
        app:
          description: Application the session should be created for
          type: string
          example: com.foo.bar
        app_version:
          description: 'Which specific version of the application to launch for the session. If

            not specified, the last published version is launched.'
          type: integer
          example: 0
        ephemeral:
          description: 'Ephemeral controls whether the session should be deleted after the client

            disconnects or not. If the containers runs into an error, the session is kept

            if with Ephemeral set to true.'
          type: boolean
          default: true
          example: false
        extra_data:
          description: Extra data passed as part of the userdata to the container
          type: string
          example: userid=123
        idle_time_min:
          description: 'Time in minutes a session stays idle without any client connected. The

            value "0" is special and causes the container to stay alive until the

            session is terminated by an API call or the container decide on its own

            to shutdown.'
          type: integer
          example: 5
        joinable:
          description: 'Makes the session joinable by another client after the initial client left.

            Requires idle_time_min to be set.'
          type: boolean
          example: true
        region:
          description: 'Region the session should be created in. If left empty a region is randomly

            selected.'
          type: string
          example: us-west-1
        screen:
          description: 'Definition of the screen dimensions. The maximum allowd screen resolution is

            4k (3840 x 2160).'
          allOf:
          - $ref: '#/components/schemas/api.Screen'
    api.SessionSharePost:
      type: object
      properties:
        expiry_min:
          description: ExpiryMin is the expiration time in minutes for the share URL
          type: integer
          default: 5
          maximum: 1
          example: 5
        type:
          description: Type is the type of the session to be shared
          type: string
          example: adb
    api.SessionsDeleteResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          type: object
          properties:
            deleted_sessions:
              description: DeletedSessions is the list of sessions IDs that were successfully deleted
              type: array
              items:
                type: string
            errors:
              description: Errors, if not empty, contains the list of sessions that failed to be deleted
              type: array
              items:
                $ref: '#/components/schemas/api.SessionsDeleteError'
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api.SessionConnectGetResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          description: Metadata contains session connection response data
          allOf:
          - $ref: '#/components/schemas/api.SessionConnectGetResponseData'
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api.SessionJoinPost:
      type: object
      properties:
        screen:
          description: 'Definition of the screen dimensions. Allows changing the dimensions the containers are configured

            with to match client expectation for the video stream. The maximum allowd screen resolution is

            4k (3840 x 2160).'
          allOf:
          - $ref: '#/components/schemas/api.Screen'
    api.SessionsDeleteError:
      type: object
      properties:
        error_message:
          description: ErrorMessage contains information about the failure
          type: string
        session_id:
          description: SessionID is the id of the session that failed to be deleted
          type: string
        status_code:
          description: StatusCode relevant to the error
          type: integer
    api.SessionsDelete:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
    api.SessionGetResponse:
      type: object
      properties:
        error:
          description: Error is an optional error message
          type: string
          example: invalid body format
        metadata:
          $ref: '#/components/schemas/api.Session'
        status:
          description: Status of the response
          enum:
          - success
          - failed
          - unknown
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseStatus'
        status_code:
          description: StatusCode is the HTTP code of the response
          type: integer
        type:
          description: Type of the operation
          enum:
          - sync
          - async
          - error
          allOf:
          - $ref: '#/components/schemas/api_gateway.ResponseType'
          example: sync
    api_gateway.ResponseType:
      type: string
      enum:
      - sync
      - async
      - error
      x-enum-varnames:
      - ResponseTypeSync
      - ResponseTypeAsync
      - ResponseTypeError