openapi.yaml

openapi: 3.1.0
info:
  title: viguno
  description: Phenotype/disease for VarFish
  contact:
    name: Manuel Holtgrewe
    email: manuel.holtgrewe@bih-charite.de
  license:
    name: Apache-2.0
  version: 0.3.2
paths:
  /api/v1/hpo/genes:
    get:
      tags:
      - hpo_genes
      summary: Query for genes in the HPO database.
      description: |-
        # Errors

        In the case that there is an error running the server.
      operationId: hpoGenes
      parameters:
      - name: gene_id
        in: query
        description: The gene ID to search for.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: gene_symbol
        in: query
        description: The gene symbol to search for.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: match_
        in: query
        description: The match mode.
        required: false
        schema:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Match'
      - name: max_results
        in: query
        description: Maximal number of results to return.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: hpo_terms
        in: query
        description: Whether to include HPO terms.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The query was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HpoGenesResult'
        '500':
          description: The server encountered an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomError'
  /api/v1/hpo/omims:
    get:
      tags:
      - hpo_omims
      summary: Query for OMIM diseases in the HPO database.
      operationId: hpoOmims
      parameters:
      - name: omim_id
        in: query
        description: The OMIM ID to search for.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: name
        in: query
        description: The disease name to search for.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: match
        in: query
        description: The match mode, default is `Match::Exact`.
        required: false
        schema:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Match'
      - name: ignore_case
        in: query
        description: Whether case is insentivie, default is `false`.
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - name: max_results
        in: query
        description: Maximal number of results to return.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: hpo_terms
        in: query
        description: Whether to include HPO terms.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The query was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HpoOmimsResult'
        '500':
          description: The server encountered an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomError'
  /api/v1/hpo/sim/term-gene:
    get:
      tags:
      - hpo_sim::term_gene
      summary: |-
        Query for similarity between a set of terms to each entry in a
        list of genes.
      operationId: hpoSimTermGene
      parameters:
      - name: terms
        in: query
        description: Set of terms to use as query.
        required: true
        schema:
          type: array
          items:
            type: string
      - name: gene_ids
        in: query
        description: The set of ids for genes to use as "database".
        required: false
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
      - name: gene_symbols
        in: query
        description: The set of symbols for genes to use as "database".
        required: false
        schema:
          type:
          - array
          - 'null'
          items:
            type: string
      responses:
        '200':
          description: The query was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HpoSimTermGeneResult'
        '500':
          description: The server encountered an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomError'
  /api/v1/hpo/sim/term-term:
    get:
      tags:
      - hpo_sim::term_term
      summary: Query for pairwise term similarity.
      description: |-
        In the case of Resnik, this corresponds to `IC(MICA(t_1, t_2))`.

        # Errors

        In the case that there is an error running the server.
      operationId: hpoSimTermTerm
      parameters:
      - name: lhs
        in: query
        description: The one set of HPO terms to compute similarity for.
        required: true
        schema:
          type: array
          items:
            type: string
      - name: rhs
        in: query
        description: The second set of HPO terms to compute similarity for.
        required: true
        schema:
          type: array
          items:
            type: string
      - name: ic_base
        in: query
        description: What should information content be based on.
        required: false
        schema:
          $ref: '#/components/schemas/IcBasedOn'
      - name: similarity
        in: query
        description: The similarity method to use.
        required: false
        schema:
          $ref: '#/components/schemas/SimilarityMethod'
      - name: combiner
        in: query
        description: The score combiner.
        required: false
        schema:
          $ref: '#/components/schemas/ScoreCombiner'
      responses:
        '200':
          description: The query was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HpoSimTermTermResult'
        '500':
          description: The server encountered an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomError'
  /api/v1/hpo/terms:
    get:
      tags:
      - hpo_terms
      summary: Query for terms in the HPO database.
      description: |-
        # Errors

        In the case that there is an error running the server.
      operationId: hpoTerms
      parameters:
      - name: term_id
        in: query
        description: The term ID to search for.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: name
        in: query
        description: The term name to search for.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: max_results
        in: query
        description: Maximal number of results to return.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: genes
        in: query
        description: Whether to include genes.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The query was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HpoTermsResult'
        '500':
          description: The server encountered an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomError'
components:
  schemas:
    CustomError:
      type: object
      required:
      - err
      properties:
        err:
          type: string
    Gene:
      type: object
      description: Struct for storing gene information in the result.
      required:
      - entrez_id
      - gene_symbol
      properties:
        entrez_id:
          type: integer
          format: int32
          description: The NCBI gene ID.
          minimum: 0
        gene_symbol:
          type: string
          description: The gene symbol.
        hgnc_id:
          type:
          - string
          - 'null'
          description: The HGNC ID.
    HpoGenesQuery:
      type: object
      description: |-
        Parameters for `fetch_hpo_genes`.

        This allows to query for genes.  The first given of the following is
        interpreted.

        - `gene_id` -- specify gene ID (either NCBI or HGNC gene ID)
        - `gene_symbol` -- specify the gene symbol
        - `max_results` -- the maximnum number of records to return
        - `hpo_terms` -- whether to include `"hpo_terms"` in result

        The following propery defines how matches are performed:

        - `match` -- how to match
      properties:
        gene_id:
          type:
          - string
          - 'null'
          description: The gene ID to search for.
        gene_symbol:
          type:
          - string
          - 'null'
          description: The gene symbol to search for.
        match_:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Match'
            description: The match mode.
        max_results:
          type: integer
          description: Maximal number of results to return.
          minimum: 0
        hpo_terms:
          type: boolean
          description: Whether to include HPO terms.
    HpoGenesResult:
      type: object
      description: Container for the result.
      required:
      - version
      - query
      - result
      properties:
        version:
          $ref: '#/components/schemas/Version'
          description: Version information.
        query:
          $ref: '#/components/schemas/HpoGenesQuery'
          description: The original query records.
        result:
          type: array
          items:
            $ref: '#/components/schemas/HpoGenesResultEntry'
          description: The resulting records for the scored genes.
    HpoGenesResultEntry:
      type: object
      description: Result entry for `handle`.
      required:
      - gene_ncbi_id
      - gene_symbol
      properties:
        gene_ncbi_id:
          type: integer
          format: int32
          description: The gene's NCBI ID.
          minimum: 0
        gene_symbol:
          type: string
          description: The gene's HGNC symbol.
        hgnc_id:
          type:
          - string
          - 'null'
          description: The gene's HGNC ID.
        hpo_terms:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ResultHpoTerm'
          description: The gene's associated HPO terms.
    HpoOmimsQuery:
      type: object
      description: |-
        Parameters for `handle`.

        This allows to query for diseases.  The first given of the following
        is interpreted.

        - `omim_id` -- specify disease ID
        - `name` -- specify the name to query for
        - `max_results` -- the maximum number of records to return
        - `hpo_terms` -- whether to include `"hpo_terms"` in result

        The following propery defines how matches are performed:

        - `match` -- how to match
      properties:
        omim_id:
          type:
          - string
          - 'null'
          description: The OMIM ID to search for.
        name:
          type:
          - string
          - 'null'
          description: The disease name to search for.
        match:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Match'
            description: The match mode, default is `Match::Exact`.
        ignore_case:
          type:
          - boolean
          - 'null'
          description: Whether case is insentivie, default is `false`.
        max_results:
          type: integer
          description: Maximal number of results to return.
          minimum: 0
        hpo_terms:
          type: boolean
          description: Whether to include HPO terms.
    HpoOmimsResult:
      type: object
      description: Container for the result.
      required:
      - version
      - query
      - result
      properties:
        version:
          $ref: '#/components/schemas/Version'
          description: Version information.
        query:
          $ref: '#/components/schemas/HpoOmimsQuery'
          description: The original query records.
        result:
          type: array
          items:
            $ref: '#/components/schemas/HpoOmimsResultEntry'
          description: The resulting records for the scored genes.
    HpoOmimsResultEntry:
      type: object
      description: Result entry for `handle`.
      required:
      - omim_id
      - name
      properties:
        omim_id:
          type: string
          description: The OMIM ID.
        name:
          type: string
          description: The OMIM disease name.
        hpo_terms:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ResultHpoTerm'
          description: The gene's associated HPO terms.
    HpoSimTermGeneQuery:
      type: object
      description: The performed query.
      required:
      - terms
      - genes
      properties:
        terms:
          type: array
          items:
            $ref: '#/components/schemas/HpoTerm'
          description: The query HPO terms.
        genes:
          type: array
          items:
            $ref: '#/components/schemas/Gene'
          description: The gene list to score.
    HpoSimTermGeneResult:
      type: object
      description: Result container data structure.
      required:
      - version
      - query
      - result
      properties:
        version:
          $ref: '#/components/schemas/Version'
          description: Version information.
        query:
          $ref: '#/components/schemas/HpoSimTermGeneQuery'
          description: The original query records.
        result:
          type: array
          items:
            $ref: '#/components/schemas/HpoSimTermGeneResultEntry'
          description: The resulting records for the scored genes.
    HpoSimTermGeneResultEntry:
      type: object
      description: Store score for a record with information on individual terms.
      required:
      - gene_symbol
      - raw_score
      properties:
        gene_symbol:
          type: string
          description: The gene symbol.
        raw_score:
          type: number
          format: float
          description: The raw Phenomizer score.
        terms:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/HpoSimTermGeneTermDetails'
          description: Details on individual terms.
    HpoSimTermGeneTermDetails:
      type: object
      description: Detailed term scores.
      required:
      - term_gene
      - score
      properties:
        term_query:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/HpoTerm'
            description: The query HPO term.
        term_gene:
          $ref: '#/components/schemas/HpoTerm'
          description: The gene's HPO term.
        score:
          type: number
          format: float
          description: The similarity score.
    HpoSimTermTermQuery:
      type: object
      description: |-
        Request as sent together with the response.

        The difference is that the `lhs` and `rhs` fields are replaced by vecs.
      required:
      - lhs
      - rhs
      properties:
        lhs:
          type: array
          items:
            type: string
          description: The one set of HPO terms to compute similarity for.
        rhs:
          type: array
          items:
            type: string
          description: The second set of HPO terms to compute similarity for.
        ic_base:
          $ref: '#/components/schemas/IcBasedOn'
          description: What should information content be based on.
        similarity:
          $ref: '#/components/schemas/SimilarityMethod'
          description: The similarity method to use.
        combiner:
          $ref: '#/components/schemas/ScoreCombiner'
          description: The score combiner.
    HpoSimTermTermResult:
      type: object
      description: Result container.
      required:
      - version
      - query
      - result
      properties:
        version:
          $ref: '#/components/schemas/Version'
          description: Version information.
        query:
          $ref: '#/components/schemas/HpoSimTermTermQuery'
          description: The original query records.
        result:
          type: array
          items:
            $ref: '#/components/schemas/HpoSimTermTermResultEntry'
          description: The resulting records for the scored genes.
    HpoSimTermTermResultEntry:
      type: object
      description: Result entry for `handle`.
      required:
      - lhs
      - rhs
      - score
      properties:
        lhs:
          type: string
          description: The lhs entry.
        rhs:
          type: string
          description: The rhs entry.
        score:
          type: number
          format: float
          description: The similarity score.
    HpoTerm:
      type: object
      description: Struct for loading an HPO term from JSON.
      required:
      - term_id
      properties:
        term_id:
          type: string
          description: The term ID.
        term_name:
          type:
          - string
          - 'null'
          description: The term name (optional).
    HpoTermsQuery:
      type: object
      description: |-
        Parameters for `handle`.

        This allows to query for terms.  The first given of the following is
        interpreted.

        - `term_id` -- specify term ID
        - `gene_symbol` -- specify the gene symbol
        - `max_results` -- the maximum number of records to return
        - `genes` -- whether to include `"genes"` in result
      properties:
        term_id:
          type:
          - string
          - 'null'
          description: The term ID to search for.
        name:
          type:
          - string
          - 'null'
          description: The term name to search for.
        max_results:
          type: integer
          description: Maximal number of results to return.
          minimum: 0
        genes:
          type: boolean
          description: Whether to include genes.
    HpoTermsResult:
      type: object
      description: Container for the result.
      required:
      - version
      - query
      - result
      properties:
        version:
          $ref: '#/components/schemas/Version'
          description: Version information.
        query:
          $ref: '#/components/schemas/HpoTermsQuery'
          description: The original query records.
        result:
          type: array
          items:
            $ref: '#/components/schemas/HpoTermsResultEntry'
          description: The resulting records for the scored genes.
    HpoTermsResultEntry:
      type: object
      description: Result entry for `fetch_hpo_genes`.
      required:
      - term_id
      - name
      properties:
        term_id:
          type: string
          description: The HPO term's ID.
        name:
          type: string
          description: The HPO term's name.
        definition:
          type:
          - string
          - 'null'
          description: Any matching description.
        synonyms:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Any matching synonyms.
        xrefs:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Any matching xref.
        genes:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ResultGene'
          description: The gene's associated HPO terms.
    IcBasedOn:
      type: string
      description: |-
        Enum for representing the information content kind.

        We replicate what is in the `hpo` create so we can put them on the command line and use
        them in HTTP queries more easily.
      enum:
      - gene
      - omim
    Match:
      type: string
      description: Specify how to perform query matches in the API calls.
      enum:
      - exact
      - prefix
      - suffix
      - contains
    ResultGene:
      type: object
      description: Representation of a gene.
      required:
      - ncbi_gene_id
      - gene_symbol
      properties:
        ncbi_gene_id:
          type: integer
          format: int32
          description: The HPO ID.
          minimum: 0
        gene_symbol:
          type: string
          description: The description.
        hgnc_id:
          type:
          - string
          - 'null'
          description: The HGNC ID.
    ResultHpoTerm:
      type: object
      description: Representation of an HPO term.
      required:
      - term_id
      - name
      properties:
        term_id:
          type: string
          description: The HPO ID.
        name:
          type: string
          description: The term name.
    ScoreCombiner:
      type: string
      description: |-
        Representation of the standard combiners from HPO.

        We replicate what is in the `hpo` create so we can put them on the command line and use
        them in HTTP queries more easily.
      enum:
      - fun-sim-avg
      - fun-sim-max
      - bma
    SimilarityMethod:
      type: string
      description: |-
        Enum for representing similarity method to use.

        We replicate what is in the `hpo` create so we can put them on the command line and use
        them in HTTP queries more easily.
      enum:
      - distance-gene
      - graph-ic
      - information-coefficient
      - jc
      - lin
      - mutation
      - relevance
      - resnik
    Version:
      type: object
      description: Version information that is returned by the HTTP server.
      required:
      - hpo
      - viguno
      properties:
        hpo:
          type: string
          description: Version of the HPO.
        viguno:
          type: string
          description: Version of the `viguno` package.