Resources and Interactions

Resource Types and Instances

FHIR is based on Resources , which are the basic building blocks for all exchanges. All exchangeable content is defined as a resource; that is, a set of resource types that describe the set of resource instances that can actually be exchanged. Resources are an instance-level representation of a healthcare entity.

All resources have the following features in common:

• A URL identifying the resource
• A common set of metadata
• A human-readable element
• A set of defined data elements
• An extensibility framework which support variation in healthcare

A different set of data elements have been defined for each type of resource. The FHIR specification currently has 145 different resource types defined.

Note: The term Resource is sometimes used without clarifying whether it refers to types or instances: the context of use makes the meaning clear.

The resource types defined in the FHIR specification focus on common use cases. More specific and richer content can be supported by defining profiles on the base resource types.

Each instance of a resource consists of:

Item	Definition
resourceType	Required. This is the type of resource.
id	The ID of the resource. This is present in every instance when a resource is exchanged except during the create operation.
meta	Usually present. This is use/context data that is common to all resources and managed by the infrastructure. It is missing if there is no metadata defined for the resource.
text	Recommended. This is XHTML that provides a human readable representation of the resource.
extension	Optional. This is one of the extensions defined by the extensibility framework.
data	Optional. These are the data elements defined for each type of resource. There is a different set for each resourceType.

Notes
   • If a resource is accessed via the FHIR RESTful API, the URL for the resource is [baseurl]/[resourceType]/[id] where the resourceType and ID come from the resource.
   • Some resources contain an explicit URL, which is normally the URL of master copy of the resource. This URL remains constant as the resource is copied across systems.
     See Canonical URLs for more information.

Interactions

The HL7 FHIR Release 4 specification defines a RESTful API for creating, reading, updating, deleting, and searching FHIR resources. Opala provides FHIR-based APIs that enable developers to access the data they need to present to their customers. Our API provides a robust Master Patient Index, Okta OAuth 2.0 security, a cloud-based data repository, and access to FHIR-based resources.

Each API request uses an HTTP method (e.g., GET POST, DELETE). For manipulating resources, FHIR provides a REST API with a rich but simple set of interaction.

Action	Interaction
Create	POST [baseurl]/path/{resourceType}
Read	GET [baseurl]/path/{resourceType}/{id}
Update	PUT [baseurl]/path/{resourceType}/{id}
Delete	DELETE [baseurl]/path/{resourceType}/{id}
Search	GET [baseurl]/path/{resourceType}?search parameters...
History	GET [baseurl]/path/{resourceType}/{id}/_history
Transaction	POST [baseurl]/path/ (POST a transaction bundle to the system)
Operation	GET [baseurl]/path/{resourceType}/{id}/${opname}

Create

To create a resource , send an HTTP POST request to the resourceType's endpoint.

Since the new resource you create will not have an ID assigned, when you submit a new resource (e.g., a new patient) to the server you ask the server to store the resource with an ID of its own choice.

After the resource has been created, the server sends a response which contains the HTTP code 201, indicating that the resource has been successfully created. A location header in the response indicates where the resource can be fetched in subsequent requests.

Read

You can read a resource by sending HTTP GET requests to the corresponding resourceType endpoint.

The server returns a single instance with the content specified for the resourceType.

Update

The update interaction creates a new current version for an existing resource, or it creates an initial version of the resource if none already exists for the given ID. The update interaction is performed by an HTTP PUT command.

When the client sends the server a new version of a resource (replacing the existing version), the server puts the new version at the location of the existing resource.

Note: There does not need to be an existing resource at {id}. If no resource exists, the server may automatically create the resource at the specified address.

The response to an update request contains metadata/status information, and optionally an OperationOutcome resource.

Delete

You can delete a resource which removes the existing resource so it is no longer found through search interactions. The delete is performed by an HTTP DELETE command.

Search

When you search for a resource , in addition to getting single known resources it is possible to find a collection of resources by searching the resourceType endpoint with a set of criteria describing the set of resources that should be retrieved, and the order they are presented in.

The interaction can be performed by several different HTTP commands. Generally, you use a GET command.

In addition to the GET-based search method, servers that support search also support a POST-based search.

The criteria is a set of HTTP parameters that specify which resources to return. For example, the search operation

returns all the prescriptions for the patient with the specified ID.

The response to a search request comprises a Bundle : that is, a list of matching resources with metadata.

History

The history interaction retrieves the history of the following:

• A particular resource
• All resources of a given type
• All resources supported by the system

The return content is a Bundle with the type set to history, containing the specified version history, sorted with the oldest versions last, and including any deleted resources.

Batch/Transaction

The batch and transaction interactions use a single HTTP request/response to submit a set of actions to perform on a server. The actions may be performed independently as a batch, or as a single atomic transaction, where the entire set of changes succeed or fail as a single entity.

A batch or transaction interaction is performed using an HTTP POST command.

The content of the POST submission is a Bundle with Bundle.type = batch or transaction.

A transaction is atomic, where all actions pass or fail together and the order of the entries doesn't matter; however, there is an inherent order in which to process the actions:

1. Any DELETE interactions
2. Any POST interactions
3. Any PUT or PATCH interaction
4. Any GET or HEAD interactions
5. Any conditional references

If any resource identities (including resolved identities from conditional updates/deletes) overlap in steps 1-3, the transaction is determined to have failed.

For a batch or a successful transaction, the response the server returns is a Bundle with type set to batch-response or transaction-response. The Bundle contains one entry for each entry in the request, in the same order submitted, with the outcome of processing the entry included. For a failed transaction, the server returns a single OperationOutcome resource instead of a Bundle.

Exchanges

The FHIR specification describes other kinds of exchanges beyond the simple RESTful API described above. These interactions including exchange of groups of resources as Documents, as Messages, and by using various types of Services.

Operations

The RESTful API defines a set of common interactions that can be performed on a repository of typed resources. In addition to these, you can use Operations defined for the specification that enable you to further manipulate the resource. For example use

to submit a Claim, Pre-Authorization or Pre-Determination (all instances of Claim resources) for adjudication.

Note: All operations are preceded by a $.

Additional Resources

• HL7 FHIR specification (0.0)
• Defined RESTful API Operations (1.5)
• Base Resource Definitions (2.26)
• Canonical URLs (2.3.0.5)
• Resource Bundle (2.36)
• RESTful API (3.1.0)
• Extended Operations on the RESTful API (3.2.0)
• Profiling FHIR (5.1.0)