RESTful API

FHIR is described as a "RESTful" specification based on common industry-level use of the term REST.

Each "resource type" has the same set of interactions defined that can be used to manage the resources in a highly granular fashion, i.e., CRUD (create, read, update and delete).

Note that in this RESTful framework, transactions are performed directly on the server resource using an HTTP request/response. The API does not directly address authentication, authorization, and audit collection. All the interactions are described for synchronous use, and an asynchronous use pattern is also defined.

The API describes the FHIR resources as a set of operations (known as "interactions") on resources where individual resource instances are managed in collections by their type. Kodjin FHIR Server provides a Capability Statement that specifies which interactions, resources, and their profiles are supported.

In addition to these interactions, there is an operations framework, which includes endpoints for validation, messaging and Documents.

Create

The create interaction creates a new resource in a server-assigned location. The create interaction is performed by an HTTP POST command as shown below:

POST [base]/[type]

The request body SHALL be a FHIR Resource of the named type. The resource needs to have an ID element (this is different from official FHIR specification where the ID is server generated). Client generated GUIDs as ids are preferable. If the request body includes a meta, the server ignores the passed versionId and lastUpdated values. Instead the server populates the meta.versionId and meta.lastUpdated with the new correct values.

The server returns a 201 Created HTTP status code, and also returns a Location header which contains the new Logical ID and Version ID of the created resource version:

Location: [base]/[type]/[id]/_history/[vid]

Read

The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET command as shown below:

GET [base]/[type]/[id]

This returns a single instance with the content specified for the resource type. Server returns an ETag header with the versionId of the resource (if versioning is supported) and a Last-Modified header.

Update

The update interaction creates a new current version for an existing resource. The update interaction is performed by an HTTP PUT command as shown:

PUT [base]/[type]/[id]

The request body SHALL be a Resource of the named type with an ID element that has an identical value to the [ID] in the URL. If no ID element is provided, or the ID doesn't match with the ID in the URL, the server responds with an HTTP 400 error code. If the request body includes a meta, the server SHALL ignore the provided versionId and lastUpdated values. It populates the meta.versionId and meta.lastUpdated with the new correct values.

If the interaction is successful and the resource was updated, the server returns a 200 OK HTTP status code. The server also returns a Location header which contains the new Logical ID and Version ID of the created resource version:

Location: [base]/[type]/[id]/_history/[vid]

where [id] and [vid] are the existing or newly created ID and version ID for the resource version.

The server returns an ETag header with the versionId and a Last-Modified header. The body of the response is the resource being updated.

Kodjin supports create as update operation, meaning that a client can PUT a resource to a location that does not yet exist on the server. In this case the server will return 201 Created status code and Location header.

Patch

As an alternative to updating an entire resource, clients can perform a patch interaction. This can be useful when a client is seeking to minimize its bandwidth utilization or in scenarios where a client has only partial access or support for a resource. The patch interaction is performed by an HTTP PATCH command as shown below:

PATCH [base]/[type]/[id]

The body of a PATCH interaction SHALL be a JSON patch document with a content type of application/json-patch+json.

curl --location --request PATCH 'https://kodjin-example.edenlab.dev//fhir/Patient/ac5b5b83-8c6a-43c9-98cd-0ce842b888ad' \
--header 'content-type: application/json-patch+json' \
--data-raw '[
  { "op": "add", "path": "/address", "value":[]},
  { "op": "add", "path": "/address/0", "value":
      {
          "use" : "home",
          "line" : ["23 thule st","avon"],
          "city" : "Springfield",
          "country" : "USA",
          "text":"23 thule st"
      }
  }
]'

Version read

The vread interaction performs a version specific read of the resource. The interaction is performed by an HTTP GET command as shown below:

GET [base]/[type]/[id]/_history/[vid]

This returns a single instance with the content specified for the resource type for that version of the resource. The returned resource SHALL have an ID element with a value that is the [id], and a meta.versionId element with a value of [vid]. Servers returns an ETag header with the versionId and a Last-Modified header.

The Version ID ("vid") is an opaque identifier that conforms to the same format requirements as a Logical ID. The ID may have been found by performing a history interaction (see below), by recording the version ID from a content location returned from a read, or from a version specific reference in a content model.

Delete

The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE command as shown below:

DELETE [base]/[type]/[id]

A delete interaction means that the resource is no longer found through a search interaction. Subsequent non-version specific reads of the resource return a 404 Not found HTTP status code when the server wishes to indicate that the resource is deleted. Upon successful deletion, or if the resource does not exist at all, the server should return a 204 No Content with no response payload.

Many resources have a status element that overlaps with the idea of deletion. Each resource type defines what the semantics of the deletion interactions are. If no documentation is provided, the deletion interaction should be understood as deleting the record of the resource, with nothing about the state of the real-world corresponding resource implied.

For servers that maintain a version history, the delete interaction does not remove a resource's version history. From a version history respect, deleting a resource is the equivalent of creating a special kind of history entry that has no content and is marked as deleted.

Conditional update

The conditional update interaction allows a client to update an existing resource based on some identification criteria, rather than by logical ID. To accomplish this, the client issues a PUT as shown:

PUT [base]/[type]?[search parameters]

When the server processes this update, it performs a search using its standard search facilities for the resource type, with the goal of resolving a single logical ID for this request. The action it takes depends on how many matches are found:

• No matches, ID provided and doesn't already exist: The server treats the interaction as an Update as Create interaction
• No matches, ID provided and already exist: The server rejects the update with a 422 error
• One Match: The server performs the update against the matching resource
• Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough

Conditional delete

The conditional delete interaction allows a client to delete an existing resource based on some selection criteria, rather than by a specific logical ID. To accomplish this, the client issues an HTTP DELETE as shown:

DELETE [base]/[type]?[search parameters]

When the server processes this delete, it performs a search as specified using the standard search facilities for the resource type. The action it takes depends on how many matches are found:

• No matches or one match: The server performs an ordinary delete on the matching resource.
• Multiple matches: A server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough.