api_v1.yaml

openapi: "3.0.2"
info:
  description: >
    Cachito is a service that stores application sources and their dependencies.
  license:
    name: "GPL-3.0"
  title: Cachito API
  version: "1.0"
servers:
  - url: /api/v1
paths:
  /status:
    get:
      summary: Get Cachito status
      description: >
        Return status of Cachito workers and services that Cachito depends on.
        Includes information about which package managers can currently be processed.
      responses:
        "200":
          description: Status information (as JSON)
          content:
            application/json:
              schema:
                type: object
                properties:
                  can_process:
                    type: object
                    additionalProperties:
                      type: boolean
                      description: Requests with this package manager can be processed
                    example: { "git-submodule": false, "gomod": false, "npm": false, "pip": false }
                  services:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Name of service
                          example: nexus
                        ok:
                          type: boolean
                          description: Service seems to be working
                          example: false
                        reason:
                          type: string
                          description: Reason why service is not working
                          example: "503: Service Unavailable"
                      required:
                        - name
                        - ok
                  workers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Name of worker
                          example: celery@5ed43ee7bba5
                        ok:
                          type: boolean
                          description: Worker seems to be functional
                          example: false
                        reason:
                          type: string
                          description: Reason why worker is not functional
                          example: Node did not respond to ping
                      required:
                        - name
                        - ok
                required:
                  - can_process
                  - services
                  - workers
  /status/short:
    get:
      summary: Get Cachito status (short)
      description: >
        If everything is working correctly (i.e. all package managers can be processed),
        return 200. Otherwise, return 503.
      responses:
        "200":
          description: Everything is working correctly
          content:
            application/json:
              example: { "ok": true }
        "503":
          description: Some issues were found, at least one package manager cannot be processed
          content:
            application/json:
              example: { "ok": false, "reason": "no workers are available" }
  /requests:
    get:
      description: Return all the Cachito requests
      parameters:
        - name: page
          in: query
          description: The specific page to view
          schema:
            type: integer
            example: 1
            default: 1
        - name: per_page
          in: query
          description: The number of requests to show per page
          schema:
            type: integer
            example: 10
            default: 10
        - name: state
          in: query
          description: The state to filter requests by
          schema:
            type: string
            example: in_progress
            default: null
        - name: verbose
          in: query
          description: Shows the same view as /requests/{id}
          schema:
            type: boolean
            example: true
            default: false
        - name: repo
          in: query
          description: A full repository URL to filter request by
          schema:
            type: string
            example: https://github.com/release-engineering/retrodep.git
            default: null
        - name: ref
          in: query
          description: A git ref to filter request by
          schema:
            type: string
            example: bc9767a71ede6e0084ae4a9e01dcd8b81c30b741
            default: null
        - name: pkg_manager
          in: query
          description: >
            Filter requests by the given pkg_manager. This argument
            can be specified multiple times, that will filter all
            requests that have the specified pkg_managers.
          schema:
            type: string
            example: gomod
            default: null
      responses:
        "200":
          description: A list of requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/Request"
                  meta:
                    $ref: "#/components/schemas/Pagination"
        "400":
          description: The query parameters are invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "awesome is not a valid request state. Valid states are: complete, failed, in_progress, stale"
        "404":
          description: No requests were found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
    post:
      description: Create a new request
      requestBody:
        description: The request to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestNew'
      security:
      - "Kerberos Authentication": []
      responses:
        "201":
          description: The request was initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestVerbose"
        "400":
          description: The input is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "The \"ref\" parameter must be a 40 character hex string"
        "403":
          description: The user is not allowed to create a request with this input
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: You are not authorized to create a request on behalf of another user
  "/requests/{id}":
    get:
      description: Return a specific Cachito request
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request to retrieve
        schema:
          type: integer
      responses:
        "200":
          description: The requested Cachito request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestVerbose"
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
    patch:
      description: Update a request (requires special authorization)
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request to update
        schema:
          type: integer
      responses:
        "200":
          description: The request was updated
        "403":
          description: The requester is not allowed to modify a request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: This API endpoint is restricted to Cachito workers
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
        "400":
          description: The input is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The input data must be a JSON object
      requestBody:
        description: The keys to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestUpdate'
      security:
      - "Kerberos Authentication": []
  "/requests/{id}/configuration-files":
    get:
      description: Return the configuration files of a request
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request to retrieve the configuration files for
        schema:
          type: integer
      responses:
        "200":
          description: The configuration files of the Cachito request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RequestConfiguration"
        "403":
          description: The requester is not allowed to add configuration files for a request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: This API endpoint is restricted to Cachito workers
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
    post:
      description: Add configuration files to the request (requires special authorization)
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request to update
        schema:
          type: integer
      responses:
        "204":
          description: The request's configuration files were updated
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
        "400":
          description: The input is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The input data must be a JSON object
      requestBody:
        description: The configuration files
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/RequestConfiguration"
      security:
      - "Kerberos Authentication": []
  "/requests/{id}/content-manifest":
    get:
      description: Return the content manifest of a request
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request to retrieve the content manifest for
        schema:
          type: integer
      responses:
        "200":
          description: The content manifest of the Cachito request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentManifest"
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
        "400":
          description: The input is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Content manifests are only available for requests in the \"complete\" or \"stale\" states"
  "/requests/{id}/environment-variables":
    get:
      description: Return information about the environment variables of a request
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request to retrieve the environment variables for
        schema:
          type: integer
      responses:
        "200":
          description: The environment variables of the Cachito request
          content:
            application/json:
              schema:
                type: object
                properties:
                  NAME:
                    $ref: "#/components/schemas/EnvironmentVariableInfo"
              example:
                GOCACHE:
                  value: deps/gomod
                  kind: path
                GOPATH:
                  value: deps/gomod
                  kind: path
                GOSUMDB:
                  value: off
                  kind: literal
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
  "/requests/{id}/download":
    get:
      description: Download a Cachito request bundle
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the Cachito request
        schema:
          type: integer
      responses:
        "200":
          description: Downloads the bundle
          headers:
            Digest:
              schema:
                type: string
              description: The base64 encoded sha256 digest of the bundle. For example, sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
          content:
            application/gzip: {}
        "404":
          description: The request wasn't found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: The requested resource was not found
        "400":
          description: The input is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "The request must be in the \"complete\" state before downloading the archive"
  "/requests/{id}/logs":
    get:
      description: Return the logs for a specific Cachito request
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the Cachito request to retrieve the logs for
          schema:
            type: integer
      responses:
        '200':
          description: The logs for the Cachito request
          content:
            text/plain:
              schema:
                type: string
              example: |-
                Processing Cachito request 1...
                Processing request...
                Done processing Cachito request 1
        '404':
          description: Either logs for Cachito requests are not enabled in Cachito, Cachito can't find the request, or the log file is missing
          application/json:
            schema:
              type: object
              properties:
                error:
                  type: string
                  example: The requested resource was not found
        '410':
          description: The logs for the Cachito request have been removed due to the request being in the stale state
          application/json:
            schema:
              type: object
              properties:
                error:
                  type: string
                  example: The logs for the Cachito request 1 no longer exist
  "/content-manifest":
    get:
      description: Return the content manifest of the specified requests
      parameters:
      - name: requests
        in: query
        required: false
        description: The comma separated IDs of the Cachito requests to retrieve the content manifest for
        schema:
          type: string
          example: [1,2,3]
      responses:
        "200":
          description: The content manifest of the Cachito requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentManifest"
        "400":
          description: Any of the input Cachito request id is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Request 1 is in state in_progress, not complete or stale."

components:
  schemas:
    Package:
      type: object
      example:
        name: github.com/op/go-logging
        type: gomod
        version: "v0.1.1"
      properties:
        name:
          type: string
          example: github.com/op/go-logging
        type:
          type: string
          example: gomod
        version:
          type: string
          example: "v0.1.1"
    PackageWithReplaces:
      allOf:
      - $ref: "#/components/schemas/Package"
      - type: object
        properties:
          replaces:
            $ref: "#/components/schemas/Package"
        required:
        - name
        - type
        - version
    PackageReplacement:
      allOf:
      - type: object
        properties:
          new_name:
            type: string
            example: gitlab.com/op/go-logging
        required:
        - name
        - type
        - version
      - $ref: "#/components/schemas/Package"
    EnvironmentVariable:
      type: object
      additionalProperties:
        type: string
      example:
        GOCACHE: deps/gomod
        GOPATH: deps/gomod
    EnvironmentVariableInfo:
      type: object
      properties:
        value:
          type: string
          description: The value of the environment variable
        kind:
          type: string
          description: The kind of the environment variable, e.g. "path" or "literal"
      required:
      - kind
      - value
    example:
      value: deps/gomod
      kind: path
    Pagination:
      type: object
      properties:
        first:
          type: string
          example: "https://cachito.domain.local/api/v1/requests?page=1&per_page=20&verbose=False"
        last:
          type: string
          example: "https://cachito.domain.local/api/v1/requests?page=3&per_page=20&verbose=False"
        next:
          type: string
          example: "https://cachito.domain.local/api/v1/requests?page=1&per_page=20&verbose=False"
        page:
          type: integer
          example: 1
        pages:
          type: integer
          example: 3
        per_page:
          type: integer
          example: 20
        previous:
          type: string
          example: null
        total:
          type: integer
          example: 45
    Purl:
      type: string
      example: "pkg:golang/github.com%2Frelease-engineering%2Fretrodep%2Fv2@v2.0.2"
    RequestBase:
      type: object
      properties:
        environment_variables:
          $ref: "#/components/schemas/EnvironmentVariable"
        flags:
          type: array
          items:
            type: string
          example:
            - some_feature
            - some_other_feature
        id:
          type: integer
          example: 1
        pkg_managers:
          type: array
          items:
            type: string
          example:
            - gomod
        ref:
          type: string
          example: "a7ac8d4c0b7fe90d51fb911511cbf6939655c877"
        repo:
          type: string
          example: "https://github.com/kubernetes/kubernetes.git"
        state:
          type: string
          example: complete
        state_reason:
          type: string
          example: Completed successfully
        updated:
          type: string
          example: "2019-09-17T19:42:47.149979"
        user:
          type: string
          example: tbrady@DOMAIN.LOCAL
    Request:
      allOf:
      - type: object
        properties:
          dependencies:
            type: integer
            example: 309
          packages:
            type: integer
            example: 1
      - $ref: "#/components/schemas/RequestBase"
    RequestConfiguration:
      type: object
      properties:
        content:
          type: any
          description: This varies based on the type
          example: IlNodXQgdXAgYnJhaW4gb3IgSSdsbCBzdGFiIHlvdSB3aXRoIGEgUS1UaXAiIC0gSG9tZXIgSi4gU2ltcHNvbg==
        path:
          type: string
          description: The relative path in the bundle that the configuration should be created at
          example: app/.npmrc
        type:
          type: string
          description: The type of the configuration file content
          example: base64
      required:
      - content
      - path
      - type
    RequestNew:
      type: object
      properties:
        dependency_replacements:
          type: array
          items:
            $ref: "#/components/schemas/PackageReplacement"
        flags:
          type: array
          items:
            type: string
            example: some_flag
        packages:
          type: object
          items:
            type: array
            items:
              type: object
          example:
            npm:
            - path: client
            - path: legacy/client
        pkg_managers:
          type: array
          items:
            type: string
            example: gomod
          description: >
            The list of package managers to use on the request. If this is not set, Cachito will
            use the configured default package managers. In most deployments, this will be
            ["gomod"]. To explicitly disable the use of any package managers, just provide an
            empty array.
          example:
          - gomod
        ref:
          type: string
          example: "a7ac8d4c0b7fe90d51fb911511cbf6939655c877"
        repo:
          type: string
          example: "https://github.com/kubernetes/kubernetes.git"
        user:
          type: string
          description: >
            The user this request is created on behalf of. This is reserved for privileged users
            that can act as a representative.
          example: tbrady@DOMAIN.LOCAL
      required:
      - ref
      - repo
    RequestUpdate:
      type: object
      properties:
        dependencies:
          type: array
          items:
            $ref: "#/components/schemas/PackageWithReplaces"
        environment_variables:
          $ref: "#/components/schemas/EnvironmentVariable"
        package:
          $ref: "#/components/schemas/Package"
        state:
          type: string
          example: complete
        state_reason:
          type: string
          example: Completed successfully
        packages_count:
          type: integer
          example: 1
        dependencies_count:
          type: integer
          example: 100
    RequestVerbose:
      allOf:
      - type: object
        properties:
          configuration_files:
            type: string
            description: The URL to the API endpoint with the configuration files
            example: "https://cachito.domain.local/api/v1/requests/1/configuration-files"
          environment_variables_info:
            type: string
            description: The URL to the API endpoint with the environment variables information
            example: "https://cachito.domain.local/api/v1/requests/1/environment-variables"
          dependencies:
            type: array
            items:
              $ref: "#/components/schemas/PackageWithReplaces"
          packages:
            type: array
            items:
              allOf:
              - $ref: "#/components/schemas/Package"
              - type: object
                properties:
                  dependencies:
                    type: array
                    items:
                      $ref: "#/components/schemas/PackageWithReplaces"
          state_history:
            type: array
            items:
              $ref: "#/components/schemas/StateHistory"
          submitted_by:
            type: string
            example: osbs@DOMAIN.LOCAL
          logs:
            type: object
            properties:
              url:
                type: string
                description: URL to fetch the logs for the request
      - $ref: "#/components/schemas/RequestBase"
    StateHistory:
      type: object
      properties:
        state:
          type: string
        state_reason:
          type: string
        updated:
          type: string
      example:
        state: complete
        state_reason: Completed successfully
        updated: "2019-09-19T19:35:15.722265"
    ContentManifest:
      type: object
      properties:
        metadata:
          type: object
          properties:
            icm_version:
              type: integer
              example: 1
            icm_spec:
              type: string
              example: "https://raw.githubusercontent.com/containerbuildsystem/\
                        atomic-reactor/f4abcfdaf8247a6b074f94fa84f3846f82d781c6/\
                        atomic_reactor/schemas/content_manifest.json"
            image_layer_index:
              type: integer
              example: -1
        image_contents:
          type: array
          items:
            type: object
            properties:
              purl:
                $ref: "#/components/schemas/Purl"
              dependencies:
                type: array
                items:
                  type: object
                  properties:
                    purl:
                      $ref: "#/components/schemas/Purl"
              sources:
                type: array
                items:
                  type: object
                  properties:
                    purl:
                      $ref: "#/components/schemas/Purl"
  securitySchemes:
    "Kerberos Authentication":
      type: http
      scheme: negotiate