RESTful APIs

Overview

openFHIR Engine is a standalone component that exposes 2 restful APIs for mapping (/openfhir/tofhir and /openfhir/toopenehr) and 3 restful APIs for state configuration (/opt, /fc/context and /fc/model). Additional APIs are exposed for Terminology.

Mappings

Once operational templates, context mappers and model mappers are correctly set up (i.e. state of the engine has been configured), you can run your mappings by invoking the following endpoints:

POST /openfhir/tofhir

Map an openEHR Composition to a FHIR Resource.

Body can either be a FLAT representation of the openEHR Composition or a Canonical JSON.

FLAT examples: https://github.com/ehrbase/openEHR_SDK/tree/develop/test-data/src/main/resources/composition/flat/simSDT/conformance

Canonical JSON examples: https://github.com/ehrbase/openEHR_SDK/tree/develop/test-data/src/main/resources/composition/canonical_json

Example request:

POST /openfhir/tofhir HTTP/1.1
Content-Type: application/json
Body: <canonical json>

POST /openfhir/tofhir?templateId=dataset_poc_rso-zl_acp HTTP/1.1
Content-Type: application/json
Body: <flat json>

Query Parameters:

templateId – If an engine can not deduce a template it (i.e. if body is NOT a canonical json), then you need to provide a template id in a query parameter. When body of the request is a canonical json, this information is present within the canonical json and a templateId query param is not required.

Response is a FHIR Resource.

POST /openfhir/toopenehr

Map a FHIR Resource to an openEHR Composition.

Body needs to be a valid FHIR Resource in a JSON format.

Response is an openEHR Composition in either a FLAT format or a Canonical JSON.

Example request:

POST /openfhir/toopenehr HTTP/1.1
Content-Type: application/json
Body: <fhir resource>

Query Parameters:

flat – If you’d like to receive response in a FLAT format instead of a canonical JSON. default is false.
templateId – For the purpose of using the correct context for mapping, the engine needs to know a template id. Template id can either come as an input query parameter or it can be deduced based on all available context mappings. If no templateId is provided in the request, the engine will check all available contexts (that were persisted as part of the state configuration) and try to find one that is able to map the incoming FHIR Resource. If more than 1 is available, it will log a message and take the first one it finds.

State configuration

Note

An alternative state configuration option is via a Bootstrapping mechanism. See more at: State configuration

Context mappers

Context mappers are yaml files representing context on which a mapping takes place. See more at FHIR Connect. Structure needs to comply to a schema available at https://github.com/better-care/fhir-connect-mapping-spec.

Body when creating/updating a context mapper is plain text, directly yaml itself.

POST /fc/context

Create a new context mapper.

Example request:

POST /fc/context HTTP/1.1
Content-Type: text/plain
Body:
      format: "0.2.0"

      openEHR:
        templateId: "Medications"
        archetypes:
          - "openEHR-EHR-OBSERVATION.medication_statement.v0"
          - "openEHR-EHR-CLUSTER.medication.v2"
          - "openEHR-EHR-CLUSTER.dosage.v2"

      fhir:
        resourceType: "Bundle"

PUT /fc/context/(uuid: context_mapper_unique_id)

Update an existing context mapper.

Example request:

PUT /fc/context/6b7fe776-e4de-49ce-849e-406b280e5338 HTTP/1.1
Content-Type: text/plain
Body:
      format: "0.2.0"

      openEHR:
        templateId: "Medications"
        archetypes:
          - "openEHR-EHR-OBSERVATION.medication_statement.v0"
          - "openEHR-EHR-CLUSTER.medication.v2"
          - "openEHR-EHR-CLUSTER.dosage.v2"

      fhir:
        resourceType: "Bundle"

Model mappers

Model mappers are yaml files representing model mappings. See more at FHIR Connect. Structure needs to comply to a schema available at https://github.com/better-care/fhir-connect-mapping-spec.

Body when creating/updating a model mapper is plain text, directly yaml itself.

POST /fc/model

Create a new model mapper.

Example request:

POST /fc/model HTTP/1.1
Content-Type: text/plain
Body:
      format: "0.0.2"
      version: "0.2.0"

      fhirConfig:
        resource: "QuestionnaireResponse"
        multiple: false

      openEhrConfig:
        archetype: "openEHR-EHR-EVALUATION.clinical_synopsis.v1"

      mappings:
        - name: "synopsis"
          with:
            fhir: "$fhirResource.item.item.answer.value"
            openehr: "$openEhrArchetype.clinical_synopsis.synopsis"
            type: "STRING"
          condition:
            targetRoot: "$fhirResource.item.item"
            targetAttribute: "linkId"
            operator: "one of"
            criteria: "[conclusion]"

PUT /fc/model/(uuid: model_mapper_unique_id)

Update an existing model mapper.

Example request:

PUT /fc/model/9ae2278a-c02b-4165-96fc-79dd91495db3 HTTP/1.1
Content-Type: text/plain
Body:
      format: "0.0.2"
      version: "0.2.0"

      fhirConfig:
        resource: "QuestionnaireResponse"
        multiple: false

      openEhrConfig:
        archetype: "openEHR-EHR-EVALUATION.clinical_synopsis.v1"

      mappings:
        - name: "synopsis"
          with:
            fhir: "$fhirResource.item.item.answer.value"
            openehr: "$openEhrArchetype.clinical_synopsis.synopsis"
            type: "STRING"
          condition:
            targetRoot: "$fhirResource.item.item"
            targetAttribute: "linkId"
            operator: "one of"
            criteria: "[conclusion]"

Operational Templates

If openFHIR Engine is not integrated (see Integrations) with an existing openEHR repository where it’s fetching/searching templates for, then they need to exist within the database of the engine itself.

POST /opt

Create a new operational template

Example request:

POST /opt HTTP/1.1
Content-Type: application/xml
Body:
      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <template xmlns="http://schemas.openehr.org/v1">
          <language>
              <terminology_id>
                  <value>ISO_639-1</value>
              </terminology_id>
              <code_string>en</code_string>
          </language>
          <description>
              <original_author id="date">2020-09-17</original_author>
              <original_author id="name">test</original_author>....

PUT /opt/(uuid: opt_unique_id)

Update an existing operational template

Example request:

PUT /opt/d07ca1b7-0d1b-4aac-82b4-cb76b9dd55e0 HTTP/1.1
Content-Type: application/xml
Body:
      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <template xmlns="http://schemas.openehr.org/v1">
          <language>
              <terminology_id>
                  <value>ISO_639-1</value>
              </terminology_id>
              <code_string>en</code_string>
          </language>
          <description>
              <original_author id="date">2020-09-17</original_author>
              <original_author id="name">test</original_author>....

GET /opt/(uuid: opt_unique_id)

Read an existing operational template

Example request:

GET /opt/d07ca1b7-0d1b-4aac-82b4-cb76b9dd55e0 HTTP/1.1
Accept: application/xml