api-spec.yaml

openapi: 3.0.3
info:
  title: ARD Reduction
  description: Reduce to ARD Level
  version: "1.5.3"
servers:
  - url: 'http://localhost:8080'
tags:
  - name: ARD Reduction
    description: Reduce GL String to ARD
  - name: CWD Reduction
    description: Reduce GL String to CWD (version 2)
  - name: MAC
    description: Expand/Collapse MAC to/from alleles
  - name: Validation
    description: Validate a GL String or Allele
  - name: DRBX Blender
    description: Blend DRBX based on DRB1 and DRB3/4/5
  - name: Broad Splits
    description: Broad Split Mappings
  - name: Database
    description: IPD-IMGT/HLA DB Information
paths:
  /version:
    get:
      tags:
        - Database
      operationId: api.version_controller
      summary: IPD-IMGT/HLA Version
      description: |
        Get IPD-IMGT/HLA DB Version and `py-ard` version used for this service
      responses:
        200:
          description: IPD-IMGT/HLA version number
          content:
            application/json:
              schema:
                properties:
                 ipd_version:
                    description: IPD-IMGT/HLA DB Version
                    type: integer
                    example: 3580
                 pyard_version:
                    description: py-ard library version
                    type: string
                    example: "1.5.0"
  /redux:
    post:
      tags:
        - ARD Reduction
      operationId: api.redux_controller
      summary: Reduce GL String at various level
      description: |
        Given a GL String and a reduction method perform Reduction.

        Valid Reduction Method:
        | Reduction Type | Description                                               |
        |----------------|-----------------------------------------------------------|
        | `G`            | Reduce to G Group Level                                   |
        | `P`            | Reduce to P Group Level                                   |
        | `lg`           | Reduce to 2 field ARD level (append `g`)                  |
        | `lgx`          | Reduce to 2 field ARD level                               |
        | `W`            | Reduce/Expand to full field(4,3,2) WHO nomenclature level |
        | `exon`         | Reduce/Expand to 3 field level                            |
        | `U2`           | Reduce to 2 field unambiguous level                       |
        | `S`            | Reduce to Serological level                               |

      requestBody:
        content:
          application/json:
            schema:
              properties:
                gl_string:
                  description: GL String
                  type: string
                  example: "A*01:01+A*01:01^B*08:ASXJP+B*07:02^C*02:02+C*07:HTGM^DPB1*28:01:01G+DPB1*296:01"
                reduction_method:
                  description: Reduction Method
                  type: string
                  enum:
                    - G
                    - P
                    - lg
                    - lgx
                    - W
                    - exon
                    - U2
                    - S
                  example: "lgx"
      responses:
        200:
          description: Reduction Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  ard:
                    description: ARD reduced version of GL String
                    type: string
                    example: "A*01:01+A*01:01^B*07:02+B*08:01^C*02:02/C*02:10+C*07:01/C*07:150Q^DPB1*28:01+DPB1*28:01"
        400:
          description: Invalid GL String Form
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Invalid HLA locus"
  /ard/{allele}:
    get:
      tags:
        - ARD Reduction
      operationId: api.lgx_controller
      summary: Reduce to ARD
      description: |
        Get ARD Reduction for an Allele
      parameters:
        - name: allele
          in: path
          description: An allele or MAC
          required: true
          schema:
            type: string
          example: "DPA1*02:07:01"
      responses:
        200:
          description: ARD Reduction Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  allele:
                    description: Allele
                    type: string
                    example: "DPA1*02:07:01"
                  ard:
                    description: ARD version
                    type: string
                    example: "DPA1*02:02"
                  ipd_version:
                    description: IPD-IMGT/HLA DB Version
                    type: integer
                    example: 3580
                  pyard_version:
                    description: py-ard library version
                    type: string
                    example: "1.2.1"

        400:
          description: Invalid Allele
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Invalid HLA locus"
  /cwd-redux:
    post:
      tags:
        - CWD Reduction
      operationId: api.cwd_redux_controller
      summary: Reduce to CWD/MAC
      description: |
        Given a GL String of Allele List or a MAC find only the CWD alleles and a corresponding
        MAC if available.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                gl_string:
                  description: GL String of Allele List or a MAC code
                  type: string
                  example: "A*26:CBJTR"
      responses:
        200:
          description: CWD Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  gl_string:
                    description: GL String of Allele List or a MAC code
                    type: string
                    example: "A*26:CBJTR"
                  cwd:
                    description: CWD reduced version of GL String
                    type: string
                    example: "A*26:01/A*25:01"
                  cwd_mac:
                    description: MAC of reduced CWD if available
                    type: string
                    example: ""
        400:
          description: Invalid GL String Form
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Invalid HLA locus"
  /mac/{allele_code}:
    get:
      tags:
        - MAC
      operationId: api.mac_expand_controller
      summary: Expand MAC (Allele Code)
      description: |
        Given a MAC Code, expand its allele components
      parameters:
        - name: allele_code
          in: path
          description: A valid MAC (Allele Code)
          required: true
          schema:
            type: string
          example: "HLA-A*01:AB"
      responses:
        200:
          description: Alleles corresponding to MAC
          content:
            application/json:
              schema:
                type: object
                properties:
                  mac:
                    description: MAC
                    type: string
                    example: "HLA-A*01:AB"
                  gl_string:
                    description: GL String version of expanded MAC
                    type: string
                    example: "HLA-A*01:01/HLA-A*01:02"
                  alleles:
                    description: Alleles corresponding to MAC
                    type: array
                    example:
                      - "HLA-A*01:01"
                      - "HLA-A*01:02"
        400:
          description: Invalid MAC Code
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: MAC Code is not valid
                    type: string
                    example: "Invalid MAC Code"
  /mac:
    post:
      tags:
        - MAC
      operationId: api.mac_lookup_controller
      summary: Lookup MAC from Alleles
      description: |
        Given a allele list as a GL String, find corresponding MAC
      requestBody:
        content:
          application/json:
            schema:
              properties:
                gl_string:
                  description: GL String version of allele list
                  type: string
                  example: "HLA-A*01:01/HLA-A*01:02"
      responses:
        200:
          description: MAC corresponding to Alleles
          content:
            application/json:
              schema:
                type: object
                properties:
                  mac:
                    description: MAC
                    type: string
                    example: "HLA-A*01:AB"
                  gl_string:
                    description: Supplied GL String
                    type: string
                    example: "HLA-A*01:01/HLA-A*01:02"
                  alleles:
                    description: Alleles corresponding to MAC
                    type: array
                    example:
                      - "HLA-A*01:01"
                      - "HLA-A*01:02"
        400:
          description: Invalid MAC Code
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: MAC Code is not valid
                    type: string
                    example: "Invalid MAC Code"
  /validate:
    post:
      tags:
        - Validation
      operationId: api.validate_controller
      summary: Validate GL String
      description: |
        Given a GL String report whether it is valid or not
      requestBody:
        content:
          application/json:
            schema:
              properties:
                gl_string:
                  description: GL String
                  type: string
                  example: "A*01:01+A*01:01^B*08:ASXJP+B*07:02^C*02:02+C*07:HTGM^DPB1*28:01:01G+DPB1*296:01"
      responses:
        200:
          description: Validation Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    description: Is GL String valid
                    type: boolean
                    example: true
        404:
          description: GL String didn't validate
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    description: Is GL String valid
                    type: boolean
                    example: false
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Provided GL String is invalid: HLA-A*01:BLAH"
                  cause:
                    description: Explanation of why the GL String is not valid
                    type: string
                    example: "HLA-A*01:BLAH is not a valid GL Allele"
        400:
          description: Invalid GL String Form
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Invalid HLA locus"
  /valid:
    get:
      tags:
        - Validation
      operationId: api.validate_controller_get
      summary: Validate GL String
      description: |
        Given a GL String report whether it is valid or not
      parameters:
        - name: gl_string
          in: query
          description: GL String
          schema:
            type: string
            example: "B*08:ASXJP+B*07:02"
      responses:
        200:
          description: Validation Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    description: Is GL String valid
                    type: boolean
                    example: true
        404:
          description: GL String didn't validate
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    description: Is GL String valid
                    type: boolean
                    example: false
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Provided GL String is invalid: HLA-A*01:BLAH"
                  cause:
                    description: Explanation of why the GL String is not valid
                    type: string
                    example: "HLA-A*01:BLAH is not a valid GL Allele"
        400:
          description: Invalid GL String Form
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "Invalid HLA locus"
  /blend:
    post:
      tags:
        - DRBX Blender
      operationId: api.drbx_blender_controller
      summary: Blend DRBX
      description: |
        Given DRB1 SLUG(Single Locus Unambiguous Genotype) and DRB3, DRB4, DRB5 alleles,
        calculate the DRBX Blended SLUG/Allele
      requestBody:
        content:
          application/json:
            schema:
              required:
                - DRB1_SLUG
              properties:
                DRB1_SLUG:
                  description: |
                    DRB1 SLUG(Single Locus Unambiguous Genotype) in GL String Format
                  type: string
                  example: "HLA-DRB1*03:01+HLA-DRB1*04:01"
                DRB3:
                  description: DRB3 Allele
                  type: string
                  example: "DRB3*01:01"
                DRB4:
                  description: DRB4 Allele
                  type: string
                  example: "DRB4*01:03"
                DRB5:
                  description: DRB5 Allele
                  type: string
                  example: ""
      responses:
        200:
          description: DRBX Blend Result
          content:
            application/json:
              schema:
                type: object
                properties:
                  DRBX_blend:
                    description: Blended DRBX Result
                    type: string
                    example: "DRB3*01:01+DRB4*01:03"
        404:
          description: DRBX Blend Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  found:
                    description: What was found
                    type: string
                    example: "DRB5 het"
                  expected:
                    description: What was expected
                    type: string
                    example: "hom"
        400:
          description: Invalid DRB Data
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Describes what went wrong
                    type: string
                    example: "All of DRB1_SLUG, DRB3, DRB4, DRB5 values not provided"
  /splits/{allele}:
    get:
      tags:
        - Broad Splits
      operationId: api.splits_controller
      summary: Search Broad Split Mapping
      description: |
        Given a broad or a split, broad/split mappings will
        be returned if available.
      parameters:
        - name: allele
          in: path
          description: A valid Allele/Serology
          required: true
          schema:
            type: string
          example: A*10
      responses:
        200:
          description: Broad/Split mapping
          content:
            application/json:
              schema:
                type: object
                properties:
                  broad:
                    description: Broad Allele
                    type: string
                    example: "A*10"
                  splits:
                    description: Corresponding Splits
                    type: array
                    example:
                      - "A*25"
                      - "A*26"
                      - "A*34"
                      - "A*66"
        404:
          description: |
            Broad/Split mapping not found for the given allele
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Mapping not found
                    type: string
                    example: "Broad/Split not found"
  /similar/{allele_prefix}:
    get:
      tags:
        - Database
      operationId: api.similar_controller
      summary: Search For Similar Alleles and MACs
      description: |
        Given a prefix of an allele or MAC, find all the alleles
        beginning with the prefix.
      parameters:
        - name: allele_prefix
          in: path
          description: |
            Prefix of an Allele/MAC with a minimum of locus and a first field
          required: true
          schema:
            type: string
          example: A*01:9
      responses:
        200:
          description: List of alleles with the given prefix
          content:
            application/json:
              schema:
                type: array
                items:
                  example:
                    - A*01:91
                    - A*01:92
                    - A*01:93
                    - A*01:94
                    - A*01:95
                    - A*01:96
                    - A*01:97
                    - A*01:98
                    - A*01:99
        404:
          description: |
            No matching alleles or MACs found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: No similar alleles
                    type: string
                    example: "No similar alleles"