adc-api.yaml

swagger: '2.0'

info:
  title: AIRR Data Commons API
  version: 1.2.0
  contact:
    name: AIRR Community
    url: 'http://www.airr-community.org/'
    email: join@airr-community.org
  description: >
    Major Version 1 of the Adaptive Immune Receptor Repertoire (AIRR)
    data repository web service application programming interface (API).
  license:
    name: Creative Commons Attribution 4.0 International
    url: https://creativecommons.org/licenses/by/4.0/

basePath: /airr/v1

definitions:
  # Info object
  info_object:
    type: object
    description: Provides information about the API response
    properties:
      title:
        type: string
      version:
        type: string
      description:
        type: string
      contact: 
        type: object
        properties:
          name:
            type: string
          url:
            type: string
          email:
            type: string
      license:
        type: object
        properties:
          name:
            type: string
          url:
            type: string

  # Service info object. This is the object returned by the /info request,
  # and provides information about the ADC repository service and its attributes and capabilities
  service_info_object:
    description: Provides information about the ADC repository service and it attributes and capabilities.
    allOf:
      - $ref: '#/definitions/info_object'
      - type: object
        properties:
          attributes:
            type: object
            properties:
              max_size:
                type: integer
              max_query_size:
                type: integer
              last_update:
                type: string
          api:
            description: Provides information about the ADC API implemented by this repository service.
            $ref: '#/definitions/info_object'
          schema:
            description: Provides information about the AIRR Schema utilized by this repository service.
            $ref: '#/definitions/info_object'

  # list of repertoires
  repertoire_list:
    type: array
    items:
      $ref: 'https://raw.githubusercontent.com/airr-community/airr-standards/v1.4.1/specs/airr-schema.yaml#/Repertoire'

  # list of facets
  facet_list:
    type: array
    items:
      type: object
      properties:
        count:
          type: integer
          
  # The response object /repertoire endpoint
  repertoire_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Repertoire:
        $ref: '#/definitions/repertoire_list'
      Facet:
        $ref: '#/definitions/facet_list'

  # list of rearrangement extension fields
  rearrangement_extension:
    description: The extended Rearrangement object with additional query fields for the ADC.
    allOf:
      - $ref: 'https://raw.githubusercontent.com/airr-community/airr-standards/v1.4.1/specs/airr-schema.yaml#/Rearrangement'
      - type: object
        properties:
          adc_v_subgroup:
            type: string
            description: >
              V subgroup of the V gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHV4).
            example: IGHV4
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: V gene subgroup
          adc_v_gene:
            type: string
            description: >
              V gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHV4-59).
            example: IGHV4-59
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: V gene
          adc_d_subgroup:
            type: string
            description: >
              D subgroup of the D gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHD3).
            example: IGHD3
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: D gene subgroup
          adc_d_gene:
            type: string
            description: >
              D gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHD3-10).
            example: IGHD3-10
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: D gene
          adc_j_subgroup:
            type: string
            description: >
              J subgroup of the J gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHJ4).
            example: IGHJ4
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: J gene subgroup
          adc_j_gene:
            type: string
            description: >
              J gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHJ4).
            example: IGHJ4
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: J gene
          adc_c_subgroup:
            type: string
            description: >
              C subgroup of the C gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHG1).
            example: IGHG1
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: C gene subgroup
          adc_c_gene:
            type: string
            description: >
              C gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHG1).
            example: IGHG1
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: C gene
          adc_annotation_cell_id:
            type: string
            description: >
              The Cell ID used by the annotation tool to annotate the Cell during data processing.
            example: AAACCTGAGCACCGCT-1
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: Tool Cell ID

  # list of rearrangement annotations
  rearrangement_list:
    type: array
    items:
      $ref: '#/definitions/rearrangement_extension'

  # The response object /rearrangement endpoint
  rearrangement_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Rearrangement:
        $ref: '#/definitions/rearrangement_list'
      Facet:
        $ref: '#/definitions/facet_list'

  # list of clone extension fields
  clone_extension:
    description: The extended Clone object with additional query fields for the ADC.
    allOf:
      - $ref: 'https://raw.githubusercontent.com/airr-community/airr-standards/v1.4.1/specs/airr-schema.yaml#/Clone'
      - type: object
        properties:
          adc_v_subgroup:
            type: string
            description: >
              V subgroup of the V gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHV4).
            example: IGHV4
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: V gene subgroup
          adc_v_gene:
            type: string
            description: >
              V gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHV4-59).
            example: IGHV4-59
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: V gene
          adc_d_subgroup:
            type: string
            description: >
              D subgroup of the D gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHD3).
            example: IGHD3
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: D gene subgroup
          adc_d_gene:
            type: string
            description: >
              D gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHD3-10).
            example: IGHD3-10
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: D gene
          adc_j_subgroup:
            type: string
            description: >
              J subgroup of the J gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHJ4).
            example: IGHJ4
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: J gene subgroup
          adc_j_gene:
            type: string
            description: >
              J gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHJ4).
            example: IGHJ4
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: J gene
          adc_c_subgroup:
            type: string
            description: >
              C subgroup of the C gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHG1).
            example: IGHG1
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: C gene subgroup
          adc_c_gene:
            type: string
            description: >
              C gene. If referring to a known reference sequence in a database, such as IMGT/GENE-DB,
              the relevant gene nomenclature should be followed (e.g., IGHG1).
            example: IGHG1
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: C gene
              
  # list of clone annotations
  clone_list:
    type: array
    items:
      $ref: '#/definitions/clone_extension'

  # The response object /clone/{clone_id} endpoint
  clone_id_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Clone:
        $ref: '#/definitions/clone_list'

  # The response object /clone endpoint
  clone_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Clone:
        $ref: '#/definitions/clone_list'
      Facet:
        $ref: '#/definitions/facet_list'

  # list of cell extension fields
  cell_extension:
    description: The extended Cell object with additional query fields for the ADC.
    allOf:
      - $ref: 'https://raw.githubusercontent.com/airr-community/airr-standards/v1.4.1/specs/airr-schema.yaml#/Cell'
      - type: object
        properties:
          adc_annotation_cell_id:
            type: string
            description: >
              The Cell ID used by the annotation tool to annotate the Cell during data processing.
            example: AAACCTGAGCACCGCT-1
            x-airr:
              nullable: true
              adc-api-optional: false
              adc-query_support: true
              name: Tool Cell ID

  # list of cell annotations
  cell_list:
    type: array
    items:
      $ref: '#/definitions/cell_extension'

  # The response object /cell/{cell_id} endpoint
  cell_id_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Cell:
        $ref: '#/definitions/cell_list'

  # The response object /cell endpoint
  cell_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Cell:
        $ref: '#/definitions/cell_list'
      Facet:
        $ref: '#/definitions/facet_list'

  # list of gene expression features
  expression_list:
    type: array
    items:
      $ref: 'https://raw.githubusercontent.com/airr-community/airr-standards/v1.4.1/specs/airr-schema.yaml#/CellExpression'

  # The response object /expression/{expression_id} endpoint
  expression_id_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      CellExpression:
        $ref: '#/definitions/expression_list'
  
  # The response object for the /expression endpoint
  expression_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      CellExpression:
        $ref: '#/definitions/expression_list'
      Facet:
        $ref: '#/definitions/facet_list'

  # list of receptor extension fields
  receptor_extension:
    description: The extended Receptor object with additional query fields for the ADC.
    allOf:
      - $ref: 'https://raw.githubusercontent.com/airr-community/airr-standards/v1.4.1/specs/airr-schema.yaml#/Receptor'

  # list of receptor annotations
  receptor_list:
    type: array
    items:
      $ref: '#/definitions/receptor_extension'

  # The response object /receptor/{receptor_id} endpoint
  receptor_id_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Receptor:
        $ref: '#/definitions/receptor_list'

  # The response object /receptor endpoint
  receptor_response:
    type: object
    properties:
      Info:
        $ref: '#/definitions/info_object'
      Receptor:
        $ref: '#/definitions/receptor_list'
      Facet:
        $ref: '#/definitions/facet_list'

  # error response
  error_response:
    type: object
    properties:
      message:
        type: string
        description: Detail about the error

schemes:
  - https
produces:
  - application/json
consumes:
  - application/x-www-form-urlencoded
  - application/json
tags:
  - name: info
    description: Service information
  - name: repertoires
    description: Queries for repertoires
  - name: rearrangements
    description: Queries for rearrangements

paths:
  /:
    x-swagger-router-controller: status
    get:
      description: |
        Service heartbeat.
      consumes:
        - application/octet-stream
      operationId: getStatus
      responses:
        '200':
          description: |
            Success.
          schema:
            type: object
            properties:
              result:
                type: string
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /info:
    x-swagger-router-controller: status
    get:
      description: |
        Service information.
      tags:
        - info
      consumes:
        - application/octet-stream
      operationId: getInfo
      responses:
        '200':
          description: |
            Success.
          schema:
            $ref: '#/definitions/service_info_object'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /repertoire/{repertoire_id}:
    x-swagger-router-controller: repertoire
    get:
      description: >
        Returns a repertoire based upon its identifier.
      tags:
        - repertoires
      consumes:
        - application/x-www-form-urlencoded
        - application/json
        - application/octet-stream
      produces:
        - application/json
      parameters:
        - name: repertoire_id
          in: path
          description: ID of repertoire to return
          required: true
          type: string
      operationId: getRepertoire
      responses:
        '200':
          description: |
            A successful call returns the repertoire data.
          schema:
            $ref: '#/definitions/repertoire_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /repertoire:
    x-swagger-router-controller: repertoire
    post:
      description: >
        This query service returns metadata about repertoires.
      tags:
        - repertoires
      parameters:
        - in: body
          name: data
          schema:
            type: object
            properties:
              filters:
                type: object
              format:
                type: string
                default: json
                enum:
                  - json
              fields:
                type: array
                items:
                  type: string
              size:
                type: integer
              from:
                type: integer
              include_fields:
                type: string
                enum:
                  - miairr
                  - airr-core
                  - airr-schema
              facets:
                type: string
      operationId: queryRepertoires
      responses:
        '200':
          description: >
            A successful call returns an array of repertoire metadata.
          schema:
            $ref: '#/definitions/repertoire_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /rearrangement/{sequence_id}:
    x-swagger-router-controller: rearrangement
    get:
      description: >
        Returns a rearrangement based upon its identifier.
      tags:
        - rearrangements
      consumes:
        - application/x-www-form-urlencoded
        - application/json
        - application/octet-stream
      produces:
        - application/json
      parameters:
        - name: sequence_id
          in: path
          description: ID of rearrangement to return
          required: true
          type: string
      operationId: getRearrangement
      responses:
        '200':
          description: >
            A successful call returns the rearrangement annotation data.
          schema:
            $ref: '#/definitions/rearrangement_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /rearrangement:
    x-swagger-router-controller: rearrangement
    post:
      description: >
        This query service returns rearrangement annotation data.
      tags:
        - rearrangements
      parameters:
        - in: body
          name: data
          schema:
            type: object
            properties:
              filters:
                type: object
              format:
                type: string
                default: json
                enum:
                  - json
                  - tsv
              fields:
                type: array
                items:
                  type: string
              size:
                type: integer
              from:
                type: integer
              include_fields:
                type: string
                enum:
                  - miairr
                  - airr-core
                  - airr-schema
              facets:
                type: string
      operationId: queryRearrangements
      responses:
        '200':
          description: >
            A successful call returns an array of rearrangement annotation data.
          schema:
            $ref: '#/definitions/rearrangement_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /clone/{clone_id}:
    x-swagger-router-controller: clone
    get:
      description: >
        Returns a clone based upon its identifier.
      tags:
        - clones
      consumes:
        - application/x-www-form-urlencoded
        - application/json
        - application/octet-stream
      produces:
        - application/json
      parameters:
        - name: clone_id
          in: path
          description: ID of clone to return
          required: true
          type: string
      operationId: getClone
      responses:
        '200':
          description: >
            A successful call returns the clone annotation data.
          schema:
            $ref: '#/definitions/clone_id_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /clone:
    x-swagger-router-controller: clone
    post:
      description: >
        This query service returns clone annotation data.
      tags:
        - clones
      parameters:
        - in: body
          name: data
          schema:
            type: object
            properties:
              filters:
                type: object
              format:
                type: string
                default: json
                enum:
                  - json
                  - tsv
              fields:
                type: array
                items:
                  type: string
              size:
                type: integer
              from:
                type: integer
              include_fields:
                type: string
                enum:
                  - miairr
                  - airr-core
                  - airr-schema
              facets:
                type: string
      operationId: queryClones
      responses:
        '200':
          description: >
            A successful call returns an array of clone annotation data.
          schema:
            $ref: '#/definitions/clone_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'


  /cell/{cell_id}:
    x-swagger-router-controller: cell
    get:
      description: >
        Returns a cell based upon its identifier.
      tags:
        - cells
      consumes:
        - application/x-www-form-urlencoded
        - application/json
        - application/octet-stream
      produces:
        - application/json
      parameters:
        - name: cell_id
          in: path
          description: ID of cell to return
          required: true
          type: string
      operationId: getCell
      responses:
        '200':
          description: >
            A successful call returns the cell annotation data.
          schema:
            $ref: '#/definitions/cell_id_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /cell:
    x-swagger-router-controller: cell
    post:
      description: >
        This query service returns cell annotation data.
      tags:
        - cells
      parameters:
        - in: body
          name: data
          schema:
            type: object
            properties:
              filters:
                type: object
              format:
                type: string
                default: json
                enum:
                  - json
                  - tsv
              fields:
                type: array
                items:
                  type: string
              size:
                type: integer
              from:
                type: integer
              include_fields:
                type: string
                enum:
                  - miairr
                  - airr-core
                  - airr-schema
              facets:
                type: string
      operationId: queryCells
      responses:
        '200':
          description: >
            A successful call returns an array of cell annotation data.
          schema:
            $ref: '#/definitions/cell_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /expression/{expression_id}:
    x-swagger-router-controller: expression
    get:
      description: >
        Returns an expression property based upon its identifier.
      tags:
        - expression
      consumes:
        - application/x-www-form-urlencoded
        - application/json
        - application/octet-stream
      produces:
        - application/json
      parameters:
        - name: expression_id
          in: path
          description: ID of expression property to return
          required: true
          type: string
      operationId: getExpression
      responses:
        '200':
          description: >
            A successful call returns the expression property data.
          schema:
            $ref: '#/definitions/expression_id_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /expression:
    x-swagger-router-controller: expression
    post:
      description: >
        This query service returns gene expression data.
      tags:
        - expression
      parameters:
        - in: body
          name: data
          schema:
            type: object
            properties:
              filters:
                type: object
              format:
                type: string
                default: json
                enum:
                  - json
                  - tsv
              fields:
                type: array
                items:
                  type: string
              size:
                type: integer
              from:
                type: integer
              include_fields:
                type: string
                enum:
                  - miairr
                  - airr-core
                  - airr-schema
              facets:
                type: string
      operationId: queryExpression
      responses:
        '200':
          description: >
            A successful call returns an array of gene expression  data.
          schema:
            $ref: '#/definitions/expression_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /receptor/{receptor_id}:
    x-swagger-router-controller: receptor
    get:
      description: >
        Returns a receptor based upon its identifier.
      tags:
        - receptors
      consumes:
        - application/x-www-form-urlencoded
        - application/json
        - application/octet-stream
      produces:
        - application/json
      parameters:
        - name: receptor_id
          in: path
          description: ID of receptor to return
          required: true
          type: string
      operationId: getReceptor
      responses:
        '200':
          description: >
            A successful call returns the receptor data.
          schema:
            $ref: '#/definitions/receptor_id_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'

  /receptor:
    x-swagger-router-controller: receptor
    post:
      description: >
        This query service returns receptor data.
      tags:
        - receptors
      parameters:
        - in: body
          name: data
          schema:
            type: object
            properties:
              filters:
                type: object
              format:
                type: string
                default: json
                enum:
                  - json
                  - tsv
              fields:
                type: array
                items:
                  type: string
              size:
                type: integer
              from:
                type: integer
              include_fields:
                type: string
                enum:
                  - miairr
                  - airr-core
                  - airr-schema
              facets:
                type: string
      operationId: queryReceptors
      responses:
        '200':
          description: >
            A successful call returns an array of receptor data.
          schema:
            $ref: '#/definitions/receptor_response'
        '400':
          description: Invalid request
          schema:
            $ref: '#/definitions/error_response'
        '500':
          description: Server error
          schema:
            $ref: '#/definitions/error_response'