The REST API at a glance

The same actions, for every resource type

FHIR's RESTful API defines the same set of interactions for every resource type. Learn the pattern once, and you can use it for patients, observations, and everything else.

A request follows one pattern

The specification writes an interaction like this: a verb, then the base, then the type, then the id. The verb is the HTTP verb for the interaction. The base is the service base URL, where the server's resources are found. The type is the name of a resource type, such as Patient. And the id is the logical id of one resource.

• VERB · The HTTP verb · What the interaction does. · bolt
• [base] · The service base URL · Where the resources live. · globe
• [type] · The resource type · For example, Patient. · box
• [id] · The logical id · One resource of that type. · key

Interactions work at three levels

Interactions work at three levels. At the instance level, one resource: read, version read, update, delete, and history. At the type level, all resources of one type: create, search, and history for that type. And at the whole system level: ask for the capabilities, send a batch or transaction, search across all resource types, and see the history of everything.

• Instance · navy
• Type · amber
• Whole system · slate

A goal, and its interaction

Match the goal to the interaction. To get a resource whose id you know, read it. To find resources that match a filter, search the type. To create a new resource and let the server assign its id, create. To change an existing resource, update it. To see how a resource has changed, ask for its history. And to ask what the server can do, get its capabilities.

• Get a resource I know the id of · read · file · navy
• Find resources that match a filter · search · search · navy
• Add a new resource · create · star · amber
• Change an existing resource · update · pencil · slate
• See how a resource changed · history · calendar · slate
• Ask what the server can do · capabilities · check · slate

A server states what it supports

A server does not have to support everything. It can choose which interactions to offer, and which resource types to support. What it must do is provide a capability statement that says which interactions and resources it supports, so a client can find out.

• It chooses · Which interactions · check
• It chooses · Which resource types · box
• It must provide · A CapabilityStatement · file

What the API leaves to security

The API defines interactions on resources. It does not directly address authentication, authorization, or audit collection. Those are covered on the security page, and they must be put in place around the API.

Check yourself

Pause and think. What must a FHIR server provide so clients can find out what it supports? The answer: a capability statement.

• A capability statement
• A list of every patient
• A copy of the specification
• An audit log

Keep these in mind

The same interactions exist for every resource type. A request is a verb, a base, a type and an id. Interactions work at instance, type and whole system level. And servers state what they support in a capability statement.

• The same interactions exist for every resource type
• A request is a verb, a base, a type and an id
• Interactions work at instance, type and system level
• Servers state what they support in a CapabilityStatement