curation-swagger-spec.yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: Haplotype Frequency Curation Service
  description: Allows to store and return haplotype frequency data
paths:
  '/hfc/{submissionId}':
    delete:
      description: Delete based on submissionId
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
      responses:
        '204':
          description: Delete Success = OK
        '404':
          description: Not Found
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
    get:
      description: Returns a submission of haplotypes
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: >-
            The submission id that the haplotype frequencies were submitted
            under
      responses:
        '200':
          description: Returns the data set containing all references
          schema:
            $ref: '#/definitions/HFCurationResponse'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/{submissionId}/haplotypes':
    get:
      description: Returns the list of haplotypes attached to the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        '200':
          description: Returns the haplotype frequency data
          schema:
            $ref: '#/definitions/HaplotypeFrequencyData'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/{submissionId}/quality':
    get:
      description: Returns the list of quality measures for the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        '200':
          description: Returns the list of quality measures for the given submission. The response body may be empty if there are no quality measures for the submission.
          schema:
            type: array
            description: List of quality measures
            items:
              $ref: '#/definitions/Quality'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/{submissionId}/cohort':
    get:
      description: Returns the list of haplotypes attached to the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        '200':
          description: Returns the cohort data and genotypes if available
          schema:
            $ref: '#/definitions/CohortData'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/{submissionId}/population':
    get:
      description: Returns the population of the given submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        '200':
          description: Returns the population
          schema:
            $ref: '#/definitions/PopulationData'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/{submissionId}/labels':
    get:
      description: Returns the labels associated to the submission
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        '200':
          description: Returns label set. The response body may be empty if there are no quality measures for the submission.
          schema:
            $ref: '#/definitions/LabelData'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/{submissionId}/scope':
    get:
      description: >-
        Returns the scope of the genotypes used for creating the submitted
        haplotypes
      parameters:
        - name: submissionId
          in: path
          type: integer
          format: int64
          required: true
          description: The submission id
      responses:
        '200':
          description: Returns scope set
          schema:
            $ref: '#/definitions/ScopeData'
        '404':
          description: Submission not found.
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc:
    post:
      description: |
        Storing of a new Haplotype Frequency set.
        The service will silently ignore any quality metrics sent for submission and calculate the supported
        ones itself.
      parameters:
        - name: HFCurationRequest
          in: body
          description: Haplotype Frequency Curation Data
          required: true
          schema:
            $ref: '#/definitions/HFCurationRequest'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/HFCurationResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
    get:
      description: |
        Gets a list of all submission data sets
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/HFCurationListResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/label:
    get:
      description: Get a list of all labels
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/LabelResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  /hfc/population:
    get:
      description: |
        Get a list of all populations
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/PopulationResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/hfc/population/{populationId}':
    get:
      description: Returns a population with its attached submissions
      parameters:
        - name: populationId
          in: path
          type: integer
          format: int64
          required: true
          description: The population id
      responses:
        '200':
          description: Returns the population including all attached submissions
          schema:
            $ref: '#/definitions/PopulationSubmissionResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  /population:
    post:
      tags:
        - Population
      summary: Create Population
      operationId: createPopulation
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: populationRequest
          description: Population Request
          required: true
          schema:
            $ref: '#/definitions/PopulationRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PopulationData'
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    get:
      tags:
        - Population
      summary: Get a list of all populations
      operationId: getAllPopulations
      produces:
        - application/json
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/PopulationResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/population/{populationId}':
    get:
      tags:
        - Population
      summary: Get Population Given an Id
      operationId: getPopulationForId
      produces:
        - application/json
      parameters:
        - name: populationId
          description: Population ID
          in: path
          type: integer
          format: int64
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/PopulationData'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /cohort:
    post:
      tags:
        - Cohort
      summary: Create Cohort
      operationId: createCohort
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: cohortRequest
          description: Cohort Request
          required: true
          schema:
            $ref: '#/definitions/CohortRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/CohortData'
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    get:
      tags:
        - Cohort
      summary: Get a list of all cohorts
      operationId: getAllCohorts
      produces:
        - application/json
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/CohortResponse'
        '500':
          $ref: '#/responses/Standard500ErrorResponse'
  '/cohort/{cohortId}':
    get:
      tags:
        - Cohort
      summary: Get Cohort Given an Id
      operationId: getCohortForId
      produces:
        - application/json
      parameters:
        - name: cohortId
          description: Cohort ID
          in: path
          type: integer
          format: int64
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/CohortData'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
definitions:
  HFCurationListResponse:
    title: HFCurationListResponse
    type: object
    properties:
      HFCurationResponses:
        type: array
        items:
          $ref: '#/definitions/HFCurationResponse'
  HFCurationResponse:
    title: HFCurationResponse
    type: object
    required:
      - SubmissionID
    properties:
      SubmissionID:
        type: integer
        format: int64
        description: Reference to a submission
      PopulationID:
        type: integer
        format: int64
        description: Reference to a population
      CohortID:
        type: integer
        format: int64
        description: References a cohort
      MethodSetID:
        type: integer
        format: int64
        description: References a method set
      LabelID:
        type: integer
        format: int64
        description: References a label
      HaplotypeListID:
        type: integer
        format: int64
        description: References a haplotype list
      ScopeID:
        type: integer
        format: int64
        description: References a scope
      AccessID:
        type: integer
        format: int64
        description: References a access controls
  PopulationSubmissionResponse:
    title: PopulationSubmissionResponse
    type: object
    properties:
      PopulationSubmissionList:
        type: array
        description: List of populations together with all attached submissions
        items:
          $ref: '#/definitions/PopulationSubmissionData'
  PopulationResponse:
    title: PopulationResponse
    type: object
    properties:
      PopulationList:
        type: array
        description: List of populations
        items:
          $ref: '#/definitions/PopulationData'
  LabelResponse:
    title:  LabelResponse
    type:  object
    properties: 
      LabelsList:
        type:  array
        description: List of labels
        items:
          $ref: '#/definitions/LabelData'
  CohortResponse:
    title:  CohortResponse
    type:  object
    properties: 
      CohortsList:
        type:  array
        description: List of cohorts
        items:
          $ref: '#/definitions/CohortData'
  HFCurationRequest:
    title: HFCurationRequest
    type: object
    required:
      - PopulationID
      - CohortID
    properties:
      PopulationID:
        type: integer
        format: int64
        description: Reference to a population
      CohortID:
        type: integer
        format: int64
        description: Cohort ID or genotype list
      MethodSetID:
        type: integer
        format: int64
        description: References a method set
      MethodData:
        $ref: '#/definitions/MethodData'
      LabelID:
        type: integer
        format: int64
        description: References a label
      LabelData:
        $ref: '#/definitions/LabelData'
      HaplotypeFrequencyDataID:
        type: string
        description: References a haplotype list
      HaplotypeFrequencyData:
        $ref: '#/definitions/HaplotypeFrequencyData'
      ScopeID:
        type: integer
        format: int64
        description: References a scope
      ScopeData:
        $ref: '#/definitions/ScopeData'
      AccessID:
        type: integer
        format: int64
        description: References a access controls
      AccessData:
        $ref: '#/definitions/AccessData'
  AccessData:
    title: AccessData
    type: object
    required:
      - typeOfAccess
    properties:
      typeOfAccess:
        type: string
        description: There will be a default license if one is not provided
  HaplotypeFrequencyData:
    title: HaplotypeFrequencyData
    type: object
    required:
      - HaplotypeFrequencyList
      - License
    properties:
      License:
        $ref: '#/definitions/License'
      ResolutionData:
        $ref: '#/definitions/ResolutionData'
      HaplotypeFrequencyList:
        title: HaplotypeFrequencyList
        type: array
        description: List of HaplotypeFrequencys
        items:
          $ref: '#/definitions/HaplotypeFrequency'
      QualityList:
        type: array
        description: List of Quality
        items:
          $ref: '#/definitions/Quality'
  HaplotypeFrequency:
    title: HaplotypeFrequency
    type: object
    required:
      - haplotypeString
      - frequency
    properties:
      haplotypeString:
        type: string
        description: GL string describing the haplotype
      frequency:
        type: number
        format: double
        description: value of frequency
      FrequencyErrorList:
        type: array
        description: List of frequency errors
        items:
          $ref: '#/definitions/FrequencyError'
  Quality:
    title: Quality
    type: object
    required:
      - value
      - typeOfQuality
    properties:
      value:
        type: number
        format: double
        description: value of quality
      typeOfQuality:
        type: string
        description: type of quality
        enum:
          - DIV_LAMBDA
          - DIV_50
          - DIV_50_REL
          - SAM_SIZE
          - SAM_POP
          - DIV_PGD
          - DIV_HEAVY_TAIL
          - RES_TRS_COUNT
          - RES_TRS
          - RES_SHARE_AMBIG
          - RES_MISS_LOCI
          - DEV_HWE
          - ERR_STD
          - ERR_SAMP_80_100
          - SUM_FREQ_GAP
          - ERR_OFFSET
          - LD_MEASURE
          - KFOLD_IMPUTE
          - KFOLD_PRED_ACTUAL
          - KFOLD_N
  ScopeData:
    title: ScopeData
    type: object
    required:
      - ScopeElement
    properties:
      ScopeElement:
        title: ScopeElement
        type: array
        description: Additional Information on genotype
        items:
          $ref: '#/definitions/ScopeElement'
  PopulationSubmissionData:
    title: PopulationSubmissionData
    description: Contains all submissions for a population
    type: object
    required:
      - population
    properties:
      population:
        $ref: '#/definitions/PopulationData'
      submissions:
        title: attached submissions
        type: array
        description: submissions that describe the population
        items:
          type: integer
          format: int64
  PopulationData:
    title: PopulationData
    type: object
    required:
      - name
    properties:
      id:
        title: id
        type: integer
        format: int64
        description: id of the population
      name:
        title: Name
        type: string
        description: Name of the population
      description:
        title: description
        type: string
        description: Description of the population
  ScopeElement:
    title: ScopeElement
    type: object
    properties:
      name:
        type: string
        description: label name
      freeName:
        type: string
        description: label name
      typeOfScope:
        type: string
        description: type of label
        enum:
          - gene
          - feature
  MethodData:
    title: MethodData
    type: object
    required:
      - MethodList
    properties:
      MethodList:
        title: Method
        type: array
        description: list of methods
        items:
          $ref: '#/definitions/Method'
  LabelData:
    title: LabelData
    type: object
    required:
      - LabelList
    properties:
      LabelList:
        type: array
        items:
          $ref: '#/definitions/Label'
  Label:
    title: Label
    type: object
    description: List of Genotypes
    properties:
      value:
        type: string
        description: label name
      typeOfLabel:
        type: string
        description: type of label
  CohortData:
    title: CohortData
    type: object
    required:
      - name
      - GenotypeList
    properties:
      GenotypeList:
        $ref: '#/definitions/GenotypeList'
      name:
        title: Name
        type: string
        description: Name of the cohort
      id:
        title: id
        type: integer
        format: int64
        description: id of the cohort
  GenotypeList:
    title: GenotypeList
    type: object
    description: List of Genotypes
    properties:
      License:
        $ref: '#/definitions/License'
      Genotype:
        title: Genotype
        type: array
        description: Additional Information on genotype
        items:
          $ref: '#/definitions/Genotype'
  Genotype:
    title: Genotype
    type: object
    required:
      - genotypeString
    properties:
      genotypeString:
        type: string
        description: GL string of the genotype
      genotypingMethods:
        title: GenotypingMethods
        type: array
        description: Additional Information on genotype
        items:
          $ref: '#/definitions/GenotypeMethod'
  GenotypeMethod:
    title: GenotypeMethod
    type: object
    description: GenotypeMethod Record
    properties:
      methodLabel:
        type: string
        description: Type of method label
        enum:
          - TYPING_METHOD
          - TYPING_REF
          - TYPING_DATE
          - TYPING_IMGT_VER
          - MIRING_REF
      methodValue:
        type: string
        description: Value of method
      methodComment:
        type: string
        description: Comment on method
      methodReference:
        type: string
        description: To be used to refer to an external source
  License:
    title: License
    type: object
    description: 'License models, there will be a default license if one is not provided'
    required:
      - typeOfLicense
    properties:
      typeOfLicense:
        type: string
        description: Type of creative commons license
        enum:
          - CC0
          - by
          - by-sa
          - by-nd
          - by-nc
          - by-nc-sa
          - by-nc-nd
  Method:
    title: Method
    type: object
    description: Method Record
    properties:
      typeOfMethod:
        type: string
        description: Type of method label
        enum:
          - EM_ALGORITHM
          - EM_VERSION
          - EM_ALG_REF
          - MAC_SERVICE
          - MAC_SER_REF
          - MAC_VERSION
          - ARS_SERVICE
          - ARS_SERV_REF
          - ARS_VERSION
          - HWE_METHOD
          - HWE_REF
          - LD_METHOD
          - LD_METHOD_REF
      methodValue:
        type: string
        description: Value of method
      methodComment:
        type: string
        description: Comment on method
      methodReference:
        type: string
        description: To be used to refer to an external source
  ResolutionData:
    title: ResolutionData
    type: array
    description: List of Method
    items:
      $ref: '#/definitions/ResolutionInfo'
  ResolutionInfo:
    title: ResolutionInfo
    properties:
      scopeElement:
        type: string
      resolution:
        type: string
        description: resolution of the data
        enum:
          - G
          - P
          - gNMDP
          - gDKMS
          - 1-Field
          - 2-Field
          - 3-Field
          - 4-Field
          - Serology
  FrequencyError:
    title: FrequencyError
    properties:
      value:
        type: number
        format: double
        description: value of error
      typeOfError:
        type: string
        description: type of error
  CohortRequest:
    title: CohortRequest
    type: object
    properties:
      CohortData:
        $ref: '#/definitions/CohortData'
  PopulationRequest:
    title: PopulationRequest
    type: object
    required:
      - name
    properties:
      name:
        type: string
      description:
        type: string
  Error:
    properties:
      code:
        type: string
      message:
        type: string
responses:
  Standard500ErrorResponse:
    description: An unexpected error ocurred
    schema:
      $ref: '#/definitions/Error'