FHIR RESTful API

Note

The features described on this page are available in all Firely Server editions.

Firely Server supports most of the features in the FHIR RESTful API.

FHIR Versions

All the operations below can be called for FHIR STU3 or FHIR R4. Firely Server supports the fhirVersion mimetype parameter and fhir version endpoint mappings for that purpose. See Multiple versions of FHIR for more information.

Create, read, update, patch, delete

These five operations to manage the contents of the Firely Server, commonly referenced by the acronym CRUD, are implemented as per the specification. Patch is implemented as FHIR Patch, as this is the most versatile one. A few limitations apply.

Firely Server enables create-on-update: If you request an update and no resource exists for the given id, the provided resource will be created under the provided id.

Firely Server can reject a resource based on Validating incoming resources.

Configuration

A conditional delete interaction may match multiple resources. You can configure the server to delete all matches, or reject the operation (effectively only allowing single matches to be deleted). Allowing multiple deletes requires support for transactions on the database (MongoDb, SQL Server or SQLite). If you allow for multiple deletes, you have to specify a maximum number of resources that can be deleted at once, to save you from accidentally deleting too many resources.

"FhirCapabilities": {
    "ConditionalDeleteOptions": {
        "ConditionalDeleteType": "Single", // Single or Multiple,
        "ConditionalDeleteMaxItems": 1
    }
}

Limitations on CRUD

  1. Simultaneous conditional creates and updates are not entirely transactional safe:

    • Two conditional updates may both result in a create, although the result of one may be a match to the other.

    • Two conditional creates may both succeed, although the result of one may be a match to the other.

    • A conditional create and a simultaneous conditional update may both result in a create, although the result of one may be a match to the other.

  2. It is not possible to bring a resource that has earlier been deleted back to life with a conditional update while providing the logical id of the resource in the request payload. This operation will result in an HTTP 409 Conflict error. As a workaround, it is possible to create a new resource (with a new logical id) by omitting the id field in the payload.

  3. Parameter _pretty is not yet supported.

  4. XML Patch and JSON Patch, as well as version-read and conditional variations of FHIR Patch are not yet supported.

Update with no changes

Updating Firely Server with a resource that is identical to an existing resource in the database will normally create a new version of that resource, along with new AuditEvent and Provenance resources if auditing is enabled. This can put extra load on the server where this is not entirely necessary. To avoid these updates that can unnecessarily increase server load and database growth, the No-Op (No Operation) plugins can be enabled. By enabling these plugins, the server acknowledges the request without making any actual modifications to the database. If an update resulted in a No-Op scenario, this can be observed in the OperationOutcome that is returned by Firely Server.

Configuration for No-Op

To make sure Firely server uses the No-Op scenario, the UpdateNoOp plugins need to be enabled in the PipelineOptions.

"PipelineOptions": {
  "PluginDirectory": "./plugins",
  "Branches": [
    {
      "Path": "/",
      "Include": [
        "Vonk.Plugin.UpdateNoOp.UpdateNoOpConfiguration",
        "Vonk.Plugin.UpdateNoOp.PatchNoOpConfiguration",
        "Vonk.Plugin.UpdateNoOp.ConditionalUpdateNoOpConfiguration",
      ]
    }
  ]

  "UpdateNoOp": {
    "AdditionalMetaToBeIgnored": [
      "security",
      "tag",
      "profile"
    ]
  }

There are three No-Op plugins available:

  • Vonk.Plugin.UpdateNoOp.UpdateNoOpConfiguration - For regular updates

  • Vonk.Plugin.UpdateNoOp.PatchNoOpConfiguration - For Patch operations

  • Vonk.Plugin.UpdateNoOp.ConditionalUpdateNoOpConfiguration - For conditional updates

By default the following meta elements are ignored during resource comparison: versionId, lastUpdated and source. You can also add security, tag and profile or any other meta element to be ignored, but it depends on your specific usage of meta. For more information see the hl7 specification.

To determine if your action resulted in a No-Op scenario, you can configure Firely Server to return an OperationOutcome. For this it is necessary to configure the Prefer Header as Firely Server does not return this response by default. The Prefer Header can be set in three ways, as per the hl7 specification:

  • return=minimal- Nothing is returned by the server

  • return=representation - The resource is returned as present in the database

  • return=OperationOutcome - Return an OperationOutcome

In the example below an OperationOutcome for a No-Op scenario is returned when the Prefer Header is set to return=OperationOutcome:

{
  "resourceType": "OperationOutcome",
  "id": "26a724d9-10e4-4a71-819e-15d52f6f821c",
  "meta": {
    "versionId": "b6063533-a93e-4cd1-bb0b-5f37381d0f20",
    "lastUpdated": "2024-02-12T11:12:40.6172822+00:00"
  },
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/dotnet-api-operation-outcome",
            "code": "5025"
          }
        ],
        "text": "No changes were performed as the provided resource contains no changes to the existing resource"
      }
    },
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "The operation was successful"
    }
  ]
}

Versioning

Firely Server keeps a full version history of every resource, including the resources on the Firely Server Administration API. Be aware that version specific searches cannot be used when SMART on FHIR is enabled in Firely Server version 5.11.0 and later versions.

History

History is supported as described in the specification, on the system, type and instance level. The _since and _count parameters are also supported. The response will be a Bundle which adheres to the BundleOptions configuration, see Search size.

Limitations on history

  1. _at parameter is not yet supported.

  2. Paging is supported, but it is not isolated from intermediate changes to resources.

  3. In Firely Server version 5.11.0 and later versions _history cannot be used when SMART on FHIR is enabled.

Batch

Batch is fully supported on the usual endpoint. You can limit the number of entries accepted in a single batch. See Protect against large input.

Note that batches are not supported in the /administration endpoint.

Transaction

Transactions are supported, but with the following limitation:

  1. The /administration endpoint does not support transactions.

You can limit the number of entries accepted in a single transaction. See Protect against large input.

Capabilities

On the Capabilities interaction (<firely-server-endpoint>/metadata) Firely Server returns a CapabilityStatement that is built dynamically from the supported ResourceTypes, SearchParameters and interactions. E.g. if you Configure Search Parameters, the SearchParameters that are actually loaded appear in the CapabilityStatement.

Not supported interactions

These interactions are not yet supported by Firely Server:

  1. HEAD

Besides that, Firely Server does not yet return the date header as specified in HTTP return values