Page Status: draft updated 2024-12-17

FHIR and REST

Page index

• General considerations
• FHIR Version
• Resource formats
• Notation
• Basepath
• URIs vs URLs and encoding of URLs
• UUID
• CRUD operations
  • Parameters and extended operations
  • Create
  • Read
  • Update
  • Delete
• Search
  • Pagination
  • Prefix in search queries
• Outcome
  • Managing returned content
  • OperationOutcome
• Sequence diagrams with HTTP response codes

General considerations

FHIR® resources are exchanged using the RESTful paradigm in the Swedish National Catalog of Organization, Offerings and Contracts. Each "resource type" has a selection of the same set of interactions defined that can be used to manage the resources in a highly granular fashion. Transactions are performed on the server resource using an HTTP request/response with required access token.

Recommended reading, in complement with this implementation guide, is the FHIR RESTful API.

FHIR Version

Supported version is FHIR R4. Supported FHIR resources and their profiles can be found under the Resources section.

Resource formats

By default FHIR has support for exchanging data both in JSON and XML format. However, since all validation of the Swedish National Catalog of Organization, Offerings and Contracts has been done using JSON, that is the recommended format for exchanging data. See HL7 FHIR Resource format

Notation

Throughout this guide the following notation is used to specify how to interact with the Swedish National Catalog of Organization, Offerings and Contracts using HTTP calls to the server. It follows the same principles as the notation used by HL7 Style Guide with a few extensions.

VERB [base]/[type]/[id]{?(name_1=[value]|&name_2=[value]){&name_3=[value]}}

• VERB The HTTP method, i.e. GET, POST, PUT.
• [xyz] Mandatory parameters are surrounded by square brackets.
• {xyz} Optional content is surrounded by curly brackets.
• (A|B)C Parentheses are used for grouping data and vertical bar as a mathematical or, in this case the meaning is "A" or "B" followed by "C".

General parameter types:

• [base] The Service Base URL, i.e. http{s}://[domain]{/[path]}.
• [type] Type of resource, e.g. Patient, MedicationRequest e.t.c..
• [id] Logical ID of an instance of a resource.
• [vid] Version ID of an instance of a resource.
• [compartment] Type of resource as a compartment.
• [parameters] Placeholder for all parameters as defined for the specific interaction.

Basepath

All examples in this implementation guide refers to a [base] in the start of an URI / URL. Base is an abbreviation of Service Base URL and takes the form https://[sub_domain].[main_domain]/[api-name]/[api-version]/[application].

For the Swedish National Catalog of Organization, Offerings and Contracts this would be https://<sub-domain>.ehalsomyndigheten.se/<api-name>/v1/fhir or https://<sub-domain>.ehalsomyndigheten.sjunet.org/<api-name>/v1/fhir.

See Test- och produktionsmiljöer hos E-hälsomyndigheten for more information.

A typical example in the guide would then look like this GET [base]/Organization?_id=123.

For more information about the basepath see HL7 Service Base URL.

URIs vs URLs and encoding or URLs

FHIR use URIs (Uniform Resource Identifier) and URLs (Uniform Resource Locator) frequently as a way to identify things and point at where things can be found. For example a code in a value set is bound to the code system where the code is defined. The code system is identified by an URI, e.g. "http://unitsofmeasure.org". An other example are FHIR profiles and extensions who has a canonical identifier in the form of an URI, e.g. "http://electronichealth.se/fhir/StructureDefinition/HVOBusiness".

An URL is an URI that acts as an address to something. In the latter example above the element is named url to reflect the idea that the specification should be available on the same address as it's identification. NB! This is not the case yet for profiles, extensions and value sets created by the National Catalog of Organization, Offerings and Contracts.

The look of an URI and the different parts in one is quite familiar to most but there are some constraints that may be less known. An URI is based on US-ASCII and characters like :/?= has a special meaning. It is important to encode an URI correctly to avoid technical issues. An example is when performing a search when the URL may be something like GET [base]/Organization?identifier=urn:oid:2.5.4.97|1234. This may or may not work in a practical scenario but to avoid issues the URL should be percent-encoded like this GET [base]/Organization?identifier%3Durn%3Aoid%3A2.5.4.97%7C1234.

More information about URIs and URLs can be found at http://hl7.org/fhir/R4/http.html#general, http://hl7.org/fhir/R4/datatypes.html and https://www.rfc-editor.org/rfc/rfc3986.

UUID

UUIDs generated by the Swedish National Catalog follows RFC 4122 type 4 and the FHIR 4 specification, with a few exceptions when type 3 is used. RFC 4122 allows UUIDs to be in both upper and lower case but FHIR states that UUID IDs shall be in lower case. UUIDs in the Swedish National Catalog of Organization, Offerings and Contracts are therefore always in lower case and all UUIDs sent to the Catalog should be in lower case.

CRUD operations

Parameters and extended operations

Resource specific request parameters and extended operations are described per resource in the section Resources.

In addition to the resource specific parameters the following generic parameters are supported.

Note: All tests performed by the Swedish eHealth Agency to verify the accuracy of the Swedish National Catalog of Organization, Offerings and Contracts has been done using JSON. The XML option is part of the FHIR spec, but the Swedish eHealth Agency should be contacted before it is used.

Create

A create interaction is performed using an HTTP POST with the resource in the body of the request.

POST [base]/[type]

The server will accept the resource in the HTTP body and create a new instance of the resource with version id 1, as long as the content meets the validation and business rules of the application. If the body contains an id element, it will be ignored. The server will always assign a new logical id.

Many fields are auto generated by the Swedish National Catalog. Such fields are usually ignored if they contain data when the resource is uploaded. Detailed documentation about business rules and logic can be found in Handbok xxxx.

If the resource was sucessfully created the server returns HTTP status 201 and a Location header which contains the new Logical Id and Version Id of the created resource. If there was an error creating the resource, due to faulty body content e.g. not compliant to the resource profile, HTTP status >=400 is returned.

Create is not supported for all resources. See the section for each resource to see supported actions.

Read

A read interaction accesses the current contents of one or several resource(s). The interaction is performed by an HTTP GET command, for example

• GET [base]/[type]/[id]
• GET [base]/Organization/54ff7817-4e4e-4215-9b90-b29a8c0c3143

The id referred to above is the logical id of the resource instance. It is possible to fetch all stand-alone resource types by logical id. Resources which are available as contained resources (see section References in Resources for more information) (e.g. HVOBusiness) cannot be fetched by their logical id.

The interaction must always include the required security access token, as described in the security chapter. The operation will return one single resource with the provided identifier, if it exists, otherwise a HTTP status 404, 410 or similar is returned if the resource doesn't exist or is inaccessible.

Update

An update interaction is performed using an HTTP PUT with the resource in the body of the request. The body resource must have an id element that has an identical value to the id in the URL.

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

The server will accept the resource in the HTTP body, as long as the content meets the validation and business rules of the application and creates a new version of the resource instance and increment the version id by 1. Update action is not supported for all resources. See the section for each resource to see supported actions.

A PUT replaces the resource in its entirety making it possible to perform a GET on a resorce, followed by some changes and finally a PUT of the changed resource. Partial updates of resources using the PATCH method is not supported.

Many fields are auto generated by the Swedish National Medication List. Such fields are usually ignored if they contain data when the resource is uploaded. Detailed documentation about business rules and logic can be found in Handbok för vård och apoteksaktörer - Nationella läkemedelslistan.

If the resource was sucessfully updated the server returns HTTP status 200 and a Location header which contains the Logical Id and Version Id of the updated resource. If there was an error updating the resource, due to faulty body content e.g. not compliant to the resource profile, HTTP status >=400 is returned.

Delete

The Swedish National Catalog of Organization, Offerings and Contracts does not support delete actions initiated from an external client. Instead the resource which is no longer valid or faulty should be updated with a status that reflects this. The supported status values are defined on each resource, e.g. "entered-in-error", "inactive" or similar. The application logic of the Swedish National Medication List will at different timeframes clear these type of faulty or outdated records.

Search

A search for information is typically performed by the HTTP GET method followed by the domain adress, the resource and optional parameters. A search is defined by using a question mark in the url.

A succesful search returns HTTP status 200 OK and a Bundle with type = searchset containing the result of the search as a collection of one or more resources.

GET [base]/[type]{?[param=value]{&[param=value]...}}

Each parameter is entered after the question mark as a series of name=value pairs separated by an ampersand.

Examples:

• To search for an organization with the logical ID 123. GET http://acme.org/fhir/Organization?_id=123
• To search for all medication requests of the patient with logical ID 123, where the medication request's status is active or cancelled. GET http://acme.org/fhir/MedicationRequest?patient._id=123&status=active,cancelled

When the logical id is known, as in the first example above, a 'read' can be performed instead.

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

Example:

• GET http://acme.org/fhir/Organization/123

Another form of search is the compartment search, where one resource is specified with it's logical ID followed by a second resource. All instances of the second resource with a relationship to the first resource will then be returned.

GET [base]/[type_1]/[logical_id]/[type_2]

Example:

• To get all businesses which are related to the organization request with the logical ID 123. GET http://acme.org/fhir/Organization/123/HealthcareService

Note: It is currently not possible to perform compartment searches with parameters.

There are many search parameters and search result parameters described in the FHIR specification, both in general and per resource. The supported subset of those parameters are specified per resource in this implementation guide. It is for example not possible to specify the sort order by the _sort parameter.

For more information about searching in FHIR see HL7 FHIR Search and HL7 FHIR HTTP Search. See also URI and URL for information about encoding of search URLs.

Pagination

This guide contains some search queries where the response is paginated in order to minimize the load on the client and server. When such a query is performed, the response Bundle will contain the first page of results as well as URLs which can be used to request additional pages. Every page of results will have URLs for requesting additional pages. Below is an example of how a response might look when requesting the third page of a paginated response.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1234,
  "link": [
    {
      "relation": "self",
      "url": "http://example.org/Patient?name=peter&page=3"
    },
    {
      "relation": "first",
      "url": "http://example.org/Patient?name=peter&page=1"
    },
    {
      "relation": "previous",
      "url": "http://example.org/Patient?name=peter&page=2"
    },
    {
      "relation": "next",
      "url": "http://example.org/Patient?name=peter&page=4"
    },
    {
      "relation": "last",
      "url": "http://example.org/Patient?name=peter&page=26"
    }
  ],
  //then the search results...
}

The link with a relation of "self" represents the current page. In order to go to the next page, the URL of the link with a relation of "next" can be used, etc.

Prefix in search queries

For ordered parameter types (number, date, and quantity), a prefix to the parameter value may be used to control the nature of the matching. Equal is defaulted if no prefix is present.

Example: GET [base]/fhir/MedicationRequest?identifier=199811162396&status=active&authoredon=ge2018-03-14

Notes on personal identification information as query parameters. Since connection is achieved through https and mutual TLS, the connection is first settled and the rest of the URL is sent as part of the corresponding HTTP request which occurs within the encrypted tunnel, hence invisible to third parties.

Outcome

Managing returned content

It is possible to specify the preferred information to be returned on a successful create or update (POST and PUT) request. The preference is specified in the header parameter Prefer. This only applies when working with standard operations. Extended operations does not support the return header. Prefer: return=minimal

Prefer: return=representation

Prefer: return=OperationOutcome

A minimal request will return an empty body. A representation request will return the created or updated resource. An operation outcome request will return an OperationsOutcome resource (see below) with information about the operation. The default behavior is minimal if no preference is specified. There is one execption, as "minimal" is not allowed for MedicationRequest. One of "representation" or "OperationOutcome" must be specified when creating or updating a MedicationRequest.

OperationOutcome

An OperationOutcome can be returned on a successful create or update request (see above) describing the result of the action (HTTP Status 2*). An OperationOutcome will also always be returned on unsuccessful requests (responses related to HTTP Status 4* or 5*).

See Error handling for more information.

Sequence diagrams with HTTP response codes

The sequence diagrams below shows HTTP response codes for the typical scenarios when accessing the Swedish National Catalog of Organization, Offerings and Contracts.

<Ersätt med diagram>