ubkg-api-spec.yaml

openapi: 3.0.3
info:
  title: UBKG API
  description: This document describes the UBKG API
  version: 1.2.0
servers:
  - url: https://ontology.api.hubmapconsortium.org/
paths:
  /codes/{code_id}/codes:
    get:
      summary: Returns a list of code_ids {Concept, Code, SAB} that code the same concept(s) as the code_id, optionally restricted to source (SAB)
      operationId: codes_code_id_codes_get
      parameters:
        - name: code_id
          in: path
          required: true
          description: The code identifier
          schema:
            type: string
            example: SNOMEDCT_US 254837009
        - name: sab
          in: query
          required: false
          description: One or more sources (SABs) to return
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              example: NCI,MDR
            default: []
      responses:
        '200':
          description: A JSON array of dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CodesCodesObj'
  /codes/{code_id}/concepts:
    get:
      operationId: codes_code_id_concepts_get
      summary: Returns a list of concepts {Concept, Prefterm} that the code_id codes
      parameters:
        - name: code_id
          in: path
          required: true
          description: The code identifier
          schema:
            type: string
            example: SNOMEDCT_US 254837009
      responses:
        '200':
          description: A JSON array of dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConceptDetail'
  /concepts/{concept_id}/codes:
    get:
      operationId: concepts_concept_id_codes_get
      summary: Returns a distinct list of code_id(s) that code the concept
      parameters:
        - name: concept_id
          in: path
          required: true
          description: The concept identifier
          schema:
            type: string
            example: C0678222
        - name: sab
          in: query
          required: false
          description: One or more sources (SABs) to return
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              example: MEDLINEPLUS,MSH,MEDCIN
            default: []
      responses:
        '200':
          description: A JSON array of code_id(s) that code the concept
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: CHV 0000052645
  /concepts/{concept_id}/concepts:
    get:
      operationId: concepts_concept_id_concepts_get
      summary: Returns a list of concepts {Sab, Relationship, Concept, Prefterm} related to the concept
      parameters:
        - name: concept_id
          in: path
          required: true
          description: The concept identifier
          schema:
            type: string
            example: C0006142
      responses:
        '200':
          description: A JSON array of {Sab, Relationship, Concept, Prefterm} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SabRelationshipConceptTerm'
  /concepts/expand:
    post:
      operationId: concepts_expand_post
      summary: Returns a unique list of concepts (Concept, Preferred Term) on all paths including starting concept (query_concept_id) restricted by list of relationship types (rel), list of relationship sources (sab), and depth of travel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConceptSabRelDepth"
            example:
              query_concept_id: C2720507
              sab: [SNOMEDCT_US, HGNC]
              rel: [isa, isa]
              depth: 2
      responses:
        '200':
          description: Return all {concept, prefterm}
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConceptPrefterm'
  /concepts/paths:
    post:
      operationId: concepts_path_post
      summary: Return all paths of the relationship pattern specified within the selected sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConceptSabRel"
            example:
              query_concept_id: C2720507
              sab: [SNOMEDCT_US, HGNC]
              rel: [isa, isa]
      responses:
        '200':
          description: Return all paths of the relationship pattern specified within the selected sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PathItemConceptRelationshipSabPrefterm'
  /concepts/shortestpaths:
    post:
      operationId: concepts_shortestpaths_post
      summary: Return all paths of the relationship pattern specified within the selected sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QconceptTconceptSabRel"
            example:
              query_concept_id: C2720507
              target_concept_id: C1272753
              sab: [SNOMEDCT_US, HGNC]
              rel: [isa, part_of]
      responses:
        '200':
          description: Return all paths of the relationship pattern specified within the selected sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PathItemConceptRelationshipSabPrefterm'
  /concepts/trees:
    post:
      operationId: concepts_trees_post
      summary: Return all paths of the relationship pattern specified within the selected sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConceptSabRelDepth"
            example:
              query_concept_id: C2720507
              sab: [SNOMEDCT_US, HGNC]
              rel: [isa, isa]
              depth: 2
      responses:
        '200':
          description: Return all paths of the relationship pattern specified within the selected sources
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PathItemConceptRelationshipSabPrefterm'
  /concepts/{concept_id}/definitions:
    get:
      operationId: concepts_concept_id_definitions_get
      summary: Returns a list of definitions {Sab, Definition} of the concept
      parameters:
        - name: concept_id
          in: path
          required: true
          description: The concept identifier
          schema:
            type: string
            example: C0006142
      responses:
        '200':
          description: A JSON array of {Sab, Definition} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SabDefinition'
  /concepts/{concept_id}/semantics:
    get:
      operationId: concepts_concept_id_semantics_get
      summary: Returns a list of semantic_types {Sty, Tui, Stn} of the concept
      parameters:
        - name: concept_id
          in: path
          required: true
          description: The concept identifier
          schema:
            type: string
            example: C0304055
      responses:
        '200':
          description: A JSON array of {Sty, Tui, Stn} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StyTuiStn'
  /semantics/{semantic_id}/semantics:
    get:
      operationId: semantics_semantic_id_semantics_get
      summary: Returns a list of semantic_types {queryTUI, querySTN ,semantic, TUI_STN} of the semantic type
      parameters:
        - name: semantic_id
          in: path
          required: true
          description: The semantic identifier
          schema:
            type: string
            example: Physical Object
      responses:
        '200':
          description: A JSON array of {queryTUI, querySTN ,semantic, TUI_STN} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QQST'
  /tui/{tui_id}/semantics:
    get:
      operationId: tui_tui_id_semantics_get
      summary: Returns a list of symantic_types {semantic, STN} of the type unique id (tui)
      parameters:
        - name: tui_id
          in: path
          required: true
          description: The TUI identifier
          schema:
            type: string
            example: T200
      responses:
        '200':
          description: A JSON array of {semantic, STN} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SemanticStn'
  /terms/{term_id}/codes:
    get:
      operationId: terms_term_id_codes_get
      summary: Returns a list of codes {TermType, Code} of the text string
      parameters:
        - name: term_id
          in: path
          required: true
          description: The term identifier
          schema:
            type: string
            example: Breast cancer
      responses:
        '200':
          description: A JSON array of {TermType, Code} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TermtypeCode'
  /terms/{term_id}/concepts:
    get:
      operationId: terms_term_id_concepts_get
      summary: Returns a list of concepts associated with the text string
      parameters:
        - name: term_id
          in: path
          required: true
          description: The term identifier
          schema:
            type: string
            example: Breast cancer
      responses:
        '200':
          description: A JSON array of concepts associated with the term
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: C0794811
  /terms/{term_id}/concepts/terms:
    get:
      operationId: terms_term_id_concepts_terms_get
      summary: Returns an expanded list of concept(s) and preferred term(s) {Concept, Term} from an exact text match 
      parameters:
        - name: term_id
          in: path
          required: true
          description: The term identifier
          schema:
            type: string
            example: Breast cancer
      responses:
        '200':
          description: A JSON array of {Concept, Term} dictionaries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConceptTerm'
  /valueset:
    get:
      operationId: valueset_get
      summary: Returns a valueset of concepts that are children (have as isa relationship) of another concept.
      parameters:
        - name: parent_sab
          in: query
          required: true
          description: the SAB of the parent concept
          schema:
            type: string
            example: HUBMAP
        - name: parent_code
          in: query
          required: true
          description: the code of the parent concept in the SAB (local ontology)
          schema:
            type: string
            example: C000530
        - name: child_sabs
          in: query
          required: true
          description: the list of SABs for child concepts, in order of preference (in case of parent concepts with cross-references)
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              example: HUSAT,SNOMEDCT_US
            default: [ ]
      responses:
        '200':
          description: A JSON array of preferred terms for child codes that have an isa relationship with the parent code
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SabCodeTerm'
components:
  schemas:
    CodesCodesObj: # Schema name
      type: object
      properties:
        concept:
          type: string
          example: C0006142
        code:
          type: string
          example: CCS 2.5
        SAB:
          type: string
          example: CCF
    ConceptDetail:    # Schema name
      type: object
      properties:
        concept:
          type: string
          example: C0006142
        prefterm:
          type: string
          example: Malignant neoplasm of breast
    ConceptSabRel:    # Schema name
      type: object
      properties:
        query_concept_id:
          type: string
          example: C2720507
        sab:
          type: array
          items:
            type: string
          example: ["SNOMEDCT_US", "HGNC"]
        rel:
          type: array
          items:
            type: string
          example: ["isa", "isa"]
    ConceptSabRelDepth:    # Schema name
      type: object
      properties:
        query_concept_id:
          type: string
          example: C2720507
        sab:
          type: array
          items:
            type: string
          example: ["SNOMEDCT_US", "HGNC"]
        rel:
          type: array
          items:
            type: string
          example: ["isa","isa"]
        depth:
          type: integer
          example: 2
    ConceptPrefterm: # Schema name
      type: object
      properties:
        concept:
          type: string
          example: C0006826
        prefterm:
          type: string
          example: Malignant Neoplasms
    ConceptTerm: # Schema name
      type: object
      properties:
        concept:
          type: string
          example: C0006826
        term:
          type: string
          example: LNC LA14283-8
    PathItemConceptRelationshipSabPrefterm: # Schema name
      type: object
      properties:
        path:
          type: string
        item:
          type: string
        concept:
          type: string
          example: C0006826
        relationship:
          type: string
          example: CHD
        sab:
          type: string
          example: ICD10AM
        prefterm:
          type: string
          example: Malignant Neoplasms
    QconceptTconceptSabRel:    # Schema name
      type: object
      properties:
        query_concept_id:
          type: string
          example: C2720507
        target_concept_id:
          type: string
          example: C1272753
        sab:
          type: array
          items:
            type: string
          example: ["SNOMEDCT_US", "HGNC"]
        rel:
          type: array
          items:
            type: string
          example: ["isa", "part_of"]
    QQST: # Schema name
      type: object
      properties:
        queryTUI:
          type: string
          example: T072
        querySTN:
          type: string
          example: A1
        semantic:
          type: string
          example: Entity
        TUI:
          type: string
          example: T071
        STN:
          type: string
          example: A
    SabDefinition: # Schema name
      type: object
      properties:
        sab:
          type: string
          example: NCI
        definition:
          type: string
          example: A primary or metastatic malignant neoplasm involving the breast. The vast majority of cases are carcinomas arising from the breast parenchyma or the nipple. Malignant breast neoplasms occur more frequently in females than in males.
    SabRelationshipConceptTerm: # Schema name
      type: object
      properties:
        sab:
          type: string
          example: ICD10AM
        relationship:
          type: string
          example: CHD
        concept:
          type: string
          example: C0006826
        prefterm:
          type: string
          example: Malignant Neoplasms
    SemanticStn: # Schema name
      type: object
      properties:
        semantic:
          type: string
          example: Entity
        STN:
          type: string
          example: A
    StyTuiStn: # Schema name
      type: object
      properties:
        sty:
          type: string
          example: Organic Chemical
        tui:
          type: string
          example: T109
        stn:
          type: string
          example: A1.4.1.2.1
    TermtypeCode: # Schema name
      type: object
      properties:
        termtype:
          type: string
          example: LA
        code:
          type: string
          example: LNC LA14283-8
    SabCodeTerm: # Schema name
      type: object
      properties:
        sab:
          type: string
          example: NCI
        code:
          type: string
          example: C16853
        term:
          type: string
          example: Microscopy