openapi: 3.2.0
info:
  description: FHIR web services used to access terminology data.
  version: 1.0.0
  title: Terminology FHIR Code System API
  termsOfService: https://ic.infoway-inforoute.ca/en/about/tou?title=8_UserReferencesAndSupports/Terms_And_License_Agreements
servers:
- url: /fhir/v1
tags:
- name: CodeSystem
paths:
  /CodeSystem:
    get:
      tags:
      - CodeSystem
      summary: Retrieves a list of code systems
      description: Retrieves a list of code systems matching the provided search criteria.
      operationId: findCodeSystems
      parameters:
      - name: auth
        description: 'basic access authentication credentials, specified as username:password and encoded using <a href=''https://www.base64encode.org/'' target=''_blank''><b>Base64</b></a> encoding. These credentials can alternatively be passed in the ''Authorization: Basic'' HTTP header.'
        in: query
        schema:
          type: string
      - name: name
        description: The name of the code system. By default, this filter matches a code system if its name equals or starts with the supplied parameter value.  Also supports the <a href='http://www.hl7.org/fhir/search.html#string'><code>:contains</code> and <code>:exact</code> modifiers</a>.
        in: query
        schema:
          type: string
      - name: _sort
        description: Indicates which order to return the results. Terminology Gateway currently only supports sorting on a single field, not chained sort rules.
        in: query
        schema:
          type: string
          enum:
          - _id
          - -_id
          - identifier
          - -identifier
          - name
          - -name
      - name: _pretty
        description: Non-standard parameter to request that responses be pretty-printed.
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleOfCodeSystems'
        '400':
          description: Invalid parameters
        '403':
          description: Missing or invalid credentials
  /CodeSystem/{id}:
    get:
      tags:
      - CodeSystem
      summary: Retrieves a single code system by id
      description: Retrieves a single code system corresponding to the provided id.
      operationId: getCodeSystem
      parameters:
      - name: auth
        description: 'basic access authentication credentials, specified as username:password and encoded using <a href=''https://www.base64encode.org/'' target=''_blank''><b>Base64</b></a> encoding. These credentials can alternatively be passed in the ''Authorization: Basic'' HTTP header.'
        in: query
        schema:
          type: string
      - name: id
        required: true
        description: The code system identifier. Either the OID or the name are considered valid identifiers.
        in: path
        schema:
          type: string
      - name: _summary
        description: Requests that the server return a subset of the resource.  Code System concepts are omitted if set to true.
        in: query
        schema:
          type: boolean
          default: false
      - name: _pretty
        description: Non-standard parameter to request that responses be pretty-printed.
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeSystem'
        '400':
          description: Invalid parameters
        '403':
          description: Missing or invalid credentials
        '404':
          description: Unknown code system identifier
  /CodeSystem/{id}/_history:
    get:
      tags:
      - CodeSystem
      summary: Retrieves the history of a particular code system
      description: Retrieves the specified version history, sorted with oldest versions last
      operationId: getCodeSystemHistory
      parameters:
      - name: auth
        description: 'basic access authentication credentials, specified as username:password and encoded using <a href=''https://www.base64encode.org/'' target=''_blank''><b>Base64</b></a> encoding. These credentials can alternatively be passed in the ''Authorization: Basic'' HTTP header.'
        in: query
        schema:
          type: string
      - name: id
        required: true
        description: The code system identifier. Either the OID or the name are considered valid identifiers.
        in: path
        schema:
          type: string
      - name: _pretty
        description: Non-standard parameter to request that responses be pretty-printed.
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleOfCodeSystems'
        '400':
          description: Invalid parameters
        '403':
          description: Missing or invalid credentials
        '404':
          description: Unknown code system identifier
  /CodeSystem/{id}/_history/{vid}:
    get:
      tags:
      - CodeSystem
      summary: Retrieves a single code system by id and version id
      description: Retrieves a single code system corresponding to the provided id and version id.
      operationId: getCodeSystemVersion
      parameters:
      - name: auth
        description: 'basic access authentication credentials, specified as username:password and encoded using <a href=''https://www.base64encode.org/'' target=''_blank''><b>Base64</b></a> encoding. These credentials can alternatively be passed in the ''Authorization: Basic'' HTTP header.'
        in: query
        schema:
          type: string
      - name: id
        required: true
        description: The code system identifier. Either the OID or the name are considered valid identifiers.
        in: path
        schema:
          type: string
      - name: vid
        required: true
        description: The code system version identifier.
        in: path
        schema:
          type: string
      - name: _summary
        description: Requests that the server return a subset of the resource.  Code System concepts are omitted if set to true.
        in: query
        schema:
          type: boolean
          default: false
      - name: _pretty
        description: Non-standard parameter to request that responses be pretty-printed.
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodeSystem'
        '400':
          description: Invalid parameters
        '403':
          description: Missing or invalid credentials
        '404':
          description: Unknown code system identifier
  /CodeSystem/$lookup:
    get:
      tags:
      - CodeSystem
      summary: Retrieves a single concept from a code system
      description: Given a code and a code system, get additional details about the concept, including definition, status, designations, and properties.
      operationId: lookupConcept
      parameters:
      - name: auth
        description: 'basic access authentication credentials, specified as username:password and encoded using <a href=''https://www.base64encode.org/'' target=''_blank''><b>Base64</b></a> encoding. These credentials can alternatively be passed in the ''Authorization: Basic'' HTTP header.'
        in: query
        schema:
          type: string
      - name: code
        description: The code that is to be located.
        in: query
        required: true
        schema:
          type: string
      - name: system
        description: The URI of the code system for the code that is to be located.  If using the code system OID, it must be in the URI format urn:oid:[oid-value]
        in: query
        required: true
        schema:
          type: string
      - name: version
        description: The version of the code system.
        in: query
        required: false
        schema:
          type: string
      - name: _pretty
        description: Non-standard parameter to request that responses be pretty-printed.
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConceptLookupResponseParameter'
        '400':
          description: Invalid parameters
        '403':
          description: Missing or invalid credentials
        '404':
          description: Unknown code, code system identifier, or code system version.
    post:
      tags:
      - CodeSystem
      summary: Retrieves a single concept from a code system
      description: Given a Coding, get additional details about the concept, including definition, status, designations, and properties.
      operationId: lookupConceptByCoding
      parameters:
      - name: auth
        description: 'basic access authentication credentials, specified as username:password and encoded using <a href=''https://www.base64encode.org/'' target=''_blank''><b>Base64</b></a> encoding. These credentials can alternatively be passed in the ''Authorization: Basic'' HTTP header.'
        in: query
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConceptLookupResponseParameter'
        '400':
          description: Invalid parameters
        '403':
          description: Missing or invalid credentials
        '404':
          description: Unknown code, code system identifier, or code system version.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodingParameter'
        description: The Parameters resource containing a Coding for the desired concept.
        required: true
components:
  schemas:
    CodingParameter:
      type: object
      required:
      - parameter
      properties:
        resourceType:
          type: string
          enum:
          - Parameters
        parameter:
          type: array
          items:
            type: object
            required:
            - name
            - valueCoding
            properties:
              name:
                type: string
                enum:
                - coding
              valueCoding:
                type: object
                required:
                - system
                - code
                properties:
                  system:
                    type: string
                    description: The URI of the code system for the code that is to be located.  If using the code system OID, it must be in the URI format urn:oid:[oid-value]
                  code:
                    type: string
                    description: The code that is to be located.
                  version:
                    type: string
                    description: The version of the code system.
    OID:
      type: object
      required:
      - id
      properties:
        id:
          type: string
    ConceptLookupResponseParameter:
      type: object
      required:
      - resourceType
      - parameter
      properties:
        resourceType:
          type: string
          enum:
          - Parameters
        parameter:
          type: array
          items:
            type: object
            required:
            - name
            properties:
              name:
                type: string
                description: The name of the response parameter.
                enum:
                - name
                - version
                - display
              valueString:
                type: string
                description: The value of the response parameter.
    CodeSystem:
      type: object
      required:
      - status
      - content
      properties:
        resourceType:
          type: string
          enum:
          - CodeSystem
        id:
          type: string
          description: Identifier of the code system as assigned by the server, in this case, an OID.
        identifier:
          $ref: '#/components/schemas/OID'
        version:
          type: string
          description: Business version of the code system
        name:
          type: string
          description: Name for this code system
        description:
          type: string
          description: Natural language description of the code system
        status:
          type: string
          enum:
          - active
          - draft
          - retired
          description: Status of this version of the code system
        language:
          type: string
          description: Primary language of the resource content
        content:
          type: string
          enum:
          - not-present
          - example
          - fragment
          - complete
          description: How much of the content of the code system - the concepts and codes it defines - are represented in this response's 'concept' array.
        property:
          type: array
          items:
            type: object
            required:
            - code
            properties:
              code:
                type: string
                description: Identifies the property on the concepts, and when referred to in operations
              description:
                type: string
                description: Why the property is defined, and/or what it conveys
              type:
                type: string
                enum:
                - string
                - code
                - coding
                - integer
                - boolean
                - dateTime
        concept:
          type: array
          description: Concepts in the code system
          items:
            type: object
            required:
            - code
            properties:
              code:
                type: string
                description: The code for this concept
              display:
                type: string
                description: The preferred display for this concept
              property:
                type: array
                items:
                  type: object
                  required:
                  - code
                  properties:
                    code:
                      type: string
                      description: Identifies the property returned
                    value:
                      type: string
                      description: The value of the property returned
    BundleOfCodeSystems:
      type: object
      properties:
        resourceType:
          type: string
          enum:
          - Bundle
        id:
          type: string
          description: local identifier of the bundle as assigned by the server
        meta:
          type: object
          properties:
            lastUpdated:
              type: string
              format: date-time
              description: when the resource last changed
          description: metadata about the bundle
        type:
          type: string
          enum:
          - searchset
          description: indicates the purpose of this bundle
        total:
          type: integer
          format: int32
          description: the total number of matches for the search
        link:
          type: array
          items:
            type: object
            properties:
              relation:
                type: string
                description: a name which details the functional use for this link - see [[http://www.iana.org/assignments/link-relations/link-relations.xhtml]]
              url:
                type: string
                description: the reference details for the link
          description: a series of links that provide context to this bundle
        entry:
          type: array
          items:
            type: object
            properties:
              fullUrl:
                type: string
                description: the absolute URL for the resource
              resource:
                $ref: '#/components/schemas/CodeSystem'
externalDocs:
  description: Find out more
  url: https://infocentral.infoway-inforoute.ca/3_Tools_and_solutions/Terminology_Tools/Terminology_Gateway