labs.yaml

openapi: 3.0.0
info:
  title: Contiamo Labs Server API
  description: >-
    The labs server API describes a REST-ful interface for interacting with labs
    server.  This includes the creation and editing of bundles and the
    deployment of bundle functions.
  version: 0.0.1
  contact:
    name: Contiamo
    url: 'https://contaimo.com'
    email: [email protected]
servers:
  - url: 'http://localhost:8881'
    description: Local development server
  - url: 'https://labs.contiamo.com/api/{version}'
    description: Hosted IaaS Labs solution
    variables:
      version:
        default: 0.0.1
paths:
  '/tenants/{tenant_id}/bundles':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getTenantBundlesList
      summary: List the available bundles for the tenant
      responses:
        '200':
          description: a list of bundles summary details
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BundleDetails'
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createTenantBundle
      summary: Create a new empty bundle
      description: |
        This will register an existing Labs Bundle that has been pushed into a git server that is publically available. The resposne will contain a deploy key in the `publicKey` field.  You must add this key to the remote git server that the bundle is hosted on.  If you are using Github, see [their documentation](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) for how to add  this key to your project.

        Once you have added the deploy key, you must POST to the deploy endpoint to force the Lab server to pull and process the bundle from git. This will also deploy any functions defined in the bundle to the OpenFaaS cluster.

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Data Science FTW"
                gitUrl:
                  type: string
                  format: url
                  example: "[email protected]:contiamo/test-bundle.git"
                tenantId:
                  type: string
                  format: uuid
                  example: "notauuid-6e3c-470f-9f9d-60214497eb12"
      responses:
        '201':
          description: new bundle created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleDetails'
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        '422':
          description: |
            validation error, bundle could not be created due to a data
            validation error
          content:
            application/json:
              schema:
                type: array
                description: array of error messages
                items:
                  type: string
                  example: Invalid email
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/tenants/{tenant_id}/bundles/{bundle_id}':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
      - name: bundle_id
        in: path
        required: true
        schema:
          type: string
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
    get:
      operationId: getBundleDetails
      summary: Get the details of the specified bundle
      responses:
        '201':
          description: bundle details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleDetails'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchBundleDetails
      summary: Update bundle instance details
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BundlePatchRequest'
      responses:
        '200':
            description: Successful update
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/BundleDetails'
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        '422':
          description: |
            validation error, bundle could not be created due to a data
            validation error
          content:
            application/json:
              schema:
                type: array
                description: array of error messages
                items:
                  type: string
                  example: Invalid email
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteTenantBundle
      summary: Delete a lab server bundle
      responses:
        '204':
          description: "Successful delete, has no response body."
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        '404':
          description: 'tenant instance not found'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/tenants/{tenant_id}/bundles/{bundle_id}/deploy':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
      - name: bundle_id
        in: path
        required: true
        schema:
          type: string
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
    post:
      operationId: deployBundleFunctions
      summary: Build and deploy the bundle functions
      description: |
        This will cause Contiamo Labs to clone the bundle, build the docker images
        for each function, and deploy these functions into the cluster.

        This process can take several minutes due to the build process.  The time is
        largely dependent on the Dockerfiles and context required to build the images.
      responses:
        '200':
          description: Bundle successfully deployed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleDeploySuccess'
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  '/tenants/{tenant_id}/bundles/{bundle_id}/edit':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
      - name: bundle_id
        in: path
        required: true
        schema:
          type: string
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
    get:
      operationId: createBundleEditEnv
      summary: Start a JupyterLab env
      responses:
        '200':
          description: bundle details
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: location of the JupyterLab instance
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: stopBundleEditEnv
      summary: Stop the JupyterLab env
      parameters:
        - name: hard_reset
          in: query
          description: Will remove both the JupyterLab session and the corresponding data volume
          schema:
            type: boolean
      responses:
        '204':
          description: "Successful stop, has no response body."
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        '404':
          description: 'tenant instance not found'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/tenants/{tenant_id}/bundles/{bundle_id}/secrets':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
      - name: bundle_id
        in: path
        required: true
        schema:
          type: string
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
    get:
      operationId: getBundleSecrets
      summary: List the secrets associated to a bundle
      responses:
        '200':
          description: A list of secrets in this bundle
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BundleSecretDetails'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: addBundleSecrete
      summary: Add a secret to this bundle
      description: |
        This will register a new secret that can then be accessed by the
        function in this bundle.

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretCreateRequest'
      responses:
        '201':
          description: Add a secret to this bundle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleSecretDetails'
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        '422':
          description: |
            validation error, secret could not be created due to a data
            validation error
          content:
            application/json:
              schema:
                type: array
                description: array of error messages
                items:
                  type: string
                  example: Secret with this name already exists
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/tenants/{tenant_id}/bundles/{bundle_id}/secrets/{secret_id}':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
      - name: bundle_id
        in: path
        required: true
        schema:
          type: string
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
      - name: secret_id
        in: path
        required: true
        schema:
          type: string
          example: 428109d7-e49f-4861-8837-4e1dcc84e659
    get:
      responses:
        '200':
          description: A secret in this bundle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleSecretDetails'
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      responses:
        '204':
          description: Delete a secret in this bundle
        '401':
          description: 'unauthorized, login requried or invalid token'
        '403':
          description: 'permission denied, user is not allowed access to this resource'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  '/tenants/{tenant_id}/bundles/{bundle_id}/functions':
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          fomrat: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
      - name: bundle_id
        in: path
        required: true
        schema:
          type: string
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
    get:
      operationId: getBundleFunctionsList
      summary: Get the list of deployed functions in the specified bundle
      responses:
        '200':
          description: functions list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FunctionDetails'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/tenants/{tenant_id}/bundles/{bundle_id}/functions/{function_id}':
      parameters:
        - name: tenant_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
        - name: bundle_id
          in: path
          required: true
          schema:
            type: string
            example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
        - name: function_id
          in: path
          required: true
          schema:
            type: string
            example: f8f3234c-feb5-49bf-bb22-b184bd57cae2
      delete:
        operationId: deleteDeployedFunction
        summary: Delete and un-deploy a specific bundle function
        responses:
          '204':
            description: "Successful delete, has no response body."
          '401':
            description: 'unauthorized, login requried or invalid token'
          '403':
            description: 'permission denied, user is not allowed access to this resource'
          '404':
            description: 'function instance not found'
          default:
            description: unexpected error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Error'
components:
  schemas:
    SecretCreateRequest:
      required:
        - bundle_id
        - name
        - value
      properties:
        bundle_id:
          type: string
          format: uuid
          example: 75295bbc-6176-46fc-9cb9-0197dc1e4728
        name:
          type: string
          pattern: ^[a-zA-Z0-9._-]+$
          maxLength: 255
          minLength: 1
          example: db_password
        value:
          type: string
          maxLength: 255
          minLength: 1
          example: super_safe_password
    BundleSecretDetails:
      properties:
        id:
          type: string
          format: uuid
          example: 59cc86f9-a23a-4943-8732-67d32696a82b
        createdAt:
          type: string
          format: date-time
        bundleId:
          type: string
          format: uuid
          example: c250431e-44ac-4630-8dea-6cb067cfa7bf
        name:
          type: string
          example: db_passwordo
    BundleDetails:
      required:
        - name
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        tenantId:
          type: string
          format: uuid
          readOnly: true
          example: 1
        name:
          type: string
          minLength: 3
          example: Data Science FTW
        gitUrl:
          type: string
          format: url
          example: [email protected]:contiamo/test-bundle.git
        branch:
          type: string
          exmaple: master
          description: the branch that is pulled during deployment
        publicKey:
          type: string
          readOnly: true
          example: ssh-rsa contiamo....
    BundlePatchRequest:
      properties:
        name:
          type: string
          minLength: 3
          example: Data Science FTW
        gitUrl:
          type: string
          format: url
          example: [email protected]:contiamo/test-bundle.git
        branch:
          type: string
          exmaple: master
          description: the branch that is pulled during deployment
    FunctionDetails:
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          example: f8f3234c-feb5-49bf-bb22-b184bd57cae2
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        bundleId:
          type: string
          format: uuid
          readOnly: true
          example: b5fa88ad-1e96-4a29-bd06-f865fcbc1659
        name:
          type: string
          minLength: 3
          readOnly: true
          example: cli_echo
        image:
          type: string
          readOnly: true
          example: "functions/alpine:latest"
        command:
          type: string
          readOnly: true
          example: "xargs echo"
        environment:
          type: object
          readOnly: true
          description: a `string` to  `string` mapping of environment varialbes to inject into the Docker container.
          example: {"PARSE_JSON": "true"}
    BundleDeploySuccess:
      properties:
        bundle:
          $ref: '#/components/schemas/BundleDetails'
        functions:
          type: array
          items:
            $ref: '#/components/schemas/FunctionDetails'

    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string