openapi: 3.0.3
info:
  title: Analytics Library REST API
  version: '0.1'
  license:
    name: Business Source License 1.1
    url: https://github.com/couchbaselabs/cb-swagger/blob/release/7.6/licenses/BSL-Couchbase.txt
  description: |
    The Analytics Library REST API is provided by the Analytics service.
    This API enables you to manage the libraries that are used to create SQL\+\+ for Analytics user-defined functions.

servers:
  - url: '{scheme}://{host}:{port}'
    description: The URL scheme, host, and port are as follows.
    variables:
      scheme:
        default: http
        description: |-
          The URL scheme.
          Use `https` for secure access.
        enum:
          - http
          - https
      host:
        default: localhost
        description: The host name or IP address of a node running the Analytics Service.
      port:
        default: "8095"
        description: |-
          The Analytics Service REST port.
          Use `18095` for secure access.
        enum:
          - "8095"
          - "18095"

paths:
  /analytics/library:
    get:
      operationId: get_collection
      summary: Read All Libraries
      description: Returns all libraries and functions.
      security:
        - AnalyticsAdmin: []
      responses:
        '200':
          description: >
            Success.
            Returns an array of objects, each of which contains information about a single library.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Libraries'
        '404':
          description: >
            Not found.
            The path may be missing its trailing slash.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /analytics/library/{scope}/{library}:
    parameters:
      - $ref: '#/components/parameters/PathLibrary'
      - $ref: '#/components/parameters/PathScope'
    post:
      operationId: post_library
      summary: Create or Update a Library
      description: >
        Creates the specified library and its associated functions.
        If the specified library exists, the existing library is overwritten.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/Body"
      security:
        - FullAdmin: []
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: delete_library
      summary: Delete a Library
      description: Deletes the specified library entirely.
      security:
        - FullAdmin: []
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '404':
          $ref: '#/components/responses/LibraryNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
 parameters:
  PathLibrary:
    name: library
    schema:
      type: string
    in: path
    required: true
    description: The name of a library.
  PathScope:
    name: scope
    schema:
      type: string
    in: path
    required: true
    description: >
      The name of the Analytics scope containing the library.


      The scope name may contain one or two identifiers, separated by a slash (/).
      You must URL-encode this parameter to escape any special characters.

 schemas:
  Libraries:
    type: object
    properties:
      scope:
        type: string
        description: >
          The name of the Analytics scope containing the library.


          The scope name may contain one or two identifiers, separated by a slash (/).
        x-has-example: true
        example: travel-sample/inventory
      hash_md5:
        type: string
        description: A MD5 hash of the library residing on the server.
      name:
        type: string
        description: The name of the library.
        x-has-example: true
        example: mylib
  Errors:
    type: object
    required:
      - error
    properties:
      error:
        type: string
        description: An error message.
  Body:
    type: object
    required:
      - data
      - type
    properties:
      data:
        type: string
        format: binary
        description: The library and all its dependencies, packaged by shiv.
      type:
        type: string
        description: The language of the library.
        enum:
          - python

 responses:
  OK:
    description: The operation was successful.
    content:
      application/json:
        schema:
          type: object
  LibraryNotFound:
    description: >
      Not found.
      The library name in the path may be incorrect.
  BadRequest:
    description: >
      Bad request.
      A parameter has an incorrect value.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Errors"
  InternalServerError:
    description: >
      Internal server error.
      Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Errors"

 securitySchemes:
  FullAdmin:
    x-displayName: Full Admin
    type: http
    scheme: basic
    description: >
      To [Create or Update a Library](#post_library) or [Delete a Library](#delete_library),
      users must have the Full Admin RBAC role.

  AnalyticsAdmin:
    x-displayName: Analytics Admin
    type: http
    scheme: basic
    description: |
      To [Read All Libraries](#get_collection), users must have one of the following RBAC roles:

      * Full Admin
      * Cluster Admin
      * Analytics Admin
