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. CRUDS (create, retrieve, update, delete, search).
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 all 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 provides a Capability Statement that specifies which interactions,resources and their profiles are supported.
Interactions:
create - Create a new resource with a client assigned id.
read - Read the current state of the resource
vread - Read the state of a specific version of the resource
update - Update an existing resource by its id (or create it if it is new)
patch - Update an existing resource by posting a set of changes to it
delete - Delete a resource
history - Retrieve the change history for a particular resource
search - Search the resource type based on some filter criteria
delete - Conditional Delete across a particular resource type based on some filter criteria
history - Retrieve the change history for a particular resource type
The syntax for understanding described http requests published here
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:
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 spec where 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:
GET [base]/[type]/[id]
This returns a single instance with the content specified for the resource type. Servers 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 disagrees 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.
Server returns an ETag header with the versionId and a Last-Modified header.
The body of the response is the resource being updated.
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:
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
Example:
curl --location --request PATCH 'https://kodjin-staging.edenlab.dev//fhir/Patient/ac5b5b83-8c6a-43c9-98cd-0ce842b888ad' \
--header 'content-type: application/json-patch+json' \
--header 'x-consumer-id: {{x-consumer-id}}' \
--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:
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.
Important: The versioning feature works only if this it is enabled in the FHIR Server. This feature require additional server resources. In the Elation EMR FHIR API is disabled.
Delete
The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE command as shown:
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.