dcpquery-api.yml

openapi: "3.0.0"

info:
  title: DCP Query Service API
  description: >
    The HCA DCP Query Service provides an interface for scientists and developers to query metadata associated with
    experimental and analysis data stored in the <a href="https://humancellatlas.org/">Human Cell Atlas</a>
    <a href="https://www.humancellatlas.org/data-sharing">Data Coordination Platform</a> (DCP). Metadata from the
    <a href="https://github.com/HumanCellAtlas/data-store">DCP Data Store</a> are indexed and stored in an
    <a href="https://aws.amazon.com/rds/aurora/">AWS Aurora</a> <a href="https://www.postgresql.org/">PostgreSQL</a>
    database. For more user documentation and example queries, see 
    <a href="https://dcpquery.readthedocs.io/">Query Service documentaton on Read the Docs</a>

    To get in touch with the DCP Query Service team, join the <code>#query-service</code> channel on the
    <a href="https://join-hca-slack.data.humancellatlas.org/">HCA Slack</a>.
  version: "0.1.0"

servers:
  - url: https://{{API_DOMAIN_NAME}}/v1

paths:
  /query:
    post:
      summary: Query the database
      description: Query the database
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Query"
      responses:
        200:
          description: Query received and processed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryResult"
        301:
          description: >
            The query is still being executed. The request is being handled asynchronously. The client should follow the
            redirect after the delay specified in the Retry-After header.
          headers:
            Retry-After:
              description: Delay in seconds. The client should follow the redirect after waiting for this duration.
              schema:
                type: integer
                format: int64
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /query_job:
    post:
      summary: >
        Submit a database query and return a query job ID.
      description: >
        Query the database. The semantics of this route are identical to `POST query`, except that it assumes
        immediately that the query will take longer than 20 seconds to execute, and returns the query job ID that can
        explicitly track the query state and result.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Query"
      responses:
        202:
          description: Query job created
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                    description: Submitted query
                  job_id:
                    type: string
                    description: Job identifier in RFC4122-compliant UUID format
                    pattern: "[A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /query_jobs/{job_id}:
    get:
      summary: Check the status of a long running query job, and retrieve its results when available.
      description: >
        Given the ID of a job returned by `POST query` or `POST query/job`, returns the status of the job and a
        reference or redirect to the query results.
      parameters:
        - name: job_id
          in: path
          description: Job identifier in RFC4122-compliant UUID format
          required: true
          schema:
            type: string
            pattern: "[A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}"
        - name: redirect_when_done
          in: query
          description: >
            If set, the response will send a `302 Found` HTTP redirect to the query results when the job is done.
          schema:
            type: boolean
        - name: redirect_when_waiting
          in: query
          description: >
            If set, and the job being described is still running, the response will be a `301 Moved` HTTP redirect back
            to this route with a Retry-After header.
          schema:
            type: boolean
      responses:
        200:
          description: Job found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueryJobDescription"
        301:
          description: >
            The query is still being executed. This is a convenience redirect back to the job description while we wait
            for the query to complete. The client should follow the redirect after the delay specified in the
            Retry-After header.
          headers:
            Retry-After:
              description: Delay in seconds. The client should follow the redirect after waiting for this duration.
              schema:
                type: integer
                format: int64
        302:
          description: >
            Query execution is complete. The client is being redirected to a JSON file containing the query results.
        404:
          description: Job not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /files/{file_uuid}/bundles:
      get:
        operationId: dcpquery.api.files.bundle.get
        summary: Get list of bundle_fqids for a given file_uuid
        description: >
          Given the UUID of a file, returns a list of bundle_fqids belonging to all the bundles the file is a part of.
        parameters:
          - name: file_uuid
            in: path
            description: Job identifier in RFC4122-compliant UUID format
            required: true
            schema:
              type: string
              pattern: "[A-Za-z0-9]{8}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{12}"
          - name: check_events
            in: query
            description: >
              If set, will check for any recent dss events and check if the file is a part of any unindexed bundles.
            schema:
              type: boolean
        responses:
          200:
            description: Bundles found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/BundleList"

          404:
            description: file not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"
          default:
            description: Unexpected error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"
  /files/schema/{schema_type}:
      get:
        operationId: dcpquery.api.files.schema_type.get
        summary: Get list of files for a given schema type and version
        description: >
          Given a schema type, and major and minor versions, returns a list of file_fqids that have a
          json body based on the schema defined by the given values
        parameters:
          - name: schema_type
            in: path
            description: Job identifier in RFC4122-compliant UUID format
            required: true
            schema:
              type: string
              pattern: "[A-Za-z0-9]+"

          - name: version
            in: query
            description: >
              Set to the major and minor versions of the schema
            schema:
              type: string
              pattern: "[0-9]+[.][0-9]+"

        responses:
          200:
            description: Matching Files Found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/FileList"
          404:
            description: Schema type not found
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"
          default:
            description: Unexpected error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"
components:
  schemas:
    Query:
      type: object
      properties:
        query:
          type: string
          description: Query to run, given as a SQL string.
        params:
          type: object
          description: >
            Parameters of the query. Supply a mapping of parameters using the _format_ or _pyformat_ parameter style.
            For example, a query to count all files over a certain size might look like
            `select count(*) from files where size > %(sz)s`. To find all files over 1TB in size, pass the following
            `params` value for this query: `{"sz": 2**30}}`.
      required:
        - query

    QueryJobDescription:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
          # TODO: reconcile with old status codes PROCESSING, COMPLETE, FAILED
          enum: [new, running, done, failed]
        results:
          type: array
      required:
        - job_id
        - status

    QueryResult:
      type: object
      description: Result of query
      properties:
        query:
          type: string
          description: Submitted query
        params:
          type: object
          description: Parameters of the submitted query
        results:
          type: array
      required:
        - query
        - params
        - results

    BundleList:
      type: object
      description: List of bundle fqids
      properties:
        file_uuid:
          type: string
          description: Submitted file_uuid
        bundle_fqids:
          type: array
          description: List of bundle fqids
      required:
        - file_uuid
        - bundle_fqids

    FileList:
      type: object
      description: List of file fqids
      properties:
        schema_type:
          type: string
          description: Submitted schema type
        schema_version:
          type: string
          description: Submitted schema version
        file_fqids:
          type: array
          description: List of file fqids
      required:
        - schema_type
        - schema_version
        - file_fqids

    Error:
      type: object
      properties:
        status:
          type: integer
          format: int32
          description: HTTP error code.
        title:
          type: string
          description: Human-readable error message.
        detail:
          type: string
          description: Exception stacktrace, if any.
      required:
        - status
        - title