General API guidance | NHS Booking Standard

Implementation guidance for developers - focusing on general API implementation guidance

Purpose

This site is intended for use by software developers looking to build a conformant NHS Booking API interface using the FHIR® standard with a focus on general API implementation guidance.

Notational conventions

The keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, ‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’, ‘RECOMMENDED’, ‘MAY’, and ‘OPTIONAL’ on this site are to be interpreted as described in RFC 2119.

General standards

Information on the technical standards that SHALL be conformed to can be found in the sections below and throughout this documentation.

Important: Any additional principles highlighted in the specification MUST take precedence over those defined in these technical standards.

Internet standards

Clients and servers SHALL be conformant to the following Internet Engineering Task Force (IETF) request for comments (RFCs), which are the principal technical standards that underpin the design and development of the internet and thus FHIR’s APIs.

transport level integration SHALL be via HTTP as defined in the following RFCs: RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234 and RFC 7235
transport level security SHALL be via TLS/HTTPS as defined in RFC 5246 and RFC 6176
HTTP Strict Transport Security (HSTS) as defined in RFC 6797 SHALL be employed to protect against protocol downgrade attacks and cookie hijacking

Roadmap: NHS Digital is currently evaluating how cross-origin resource sharing (CORS) will be handled for web and mobile based applications.

RESTful API

The RESTful API described in the FHIR® standard is built on top of the Hypertext Transfer Protocol (HTTP) with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) commonly used by web browsers. Furthermore, FHIR exposes resources (and operations) as Uniform Resource Identifiers (URIs). For example, a Patient resource /fhir/Patient/1, can be operated upon using standard HTTP verbs such as DELETE /fhir/Patient/1 to remove the patient record.

The FHIR RESTful API style guide defines the following URL conventions which are used throughout the remainder of this document:

URL pattern content surrounded by [ ] are mandatory.
URL pattern content surrounded by { } are optional.

Service Root URL

The Service Root URL is the root address of where the resources defined by a capability are found.

The Service Root URL is the [base] portion of FHIR URLs.

It is important to note that the Service Root URL will be different for each Care Connect capability. Each capability’s Service Root URL may have a different URL path, or point to a different server, or a completely different supplier system.

Important: All URLs (and ids that form part of the URL) defined by this specification are case sensitive.

Service Root URL versioning

Service Root URLs SHALL be aligned with the Care Connect specification they were built against, specifically the major version number SHALL be present in the server’s Service Root URL to provide a clear distinction between API versions that are incompatible (i.e. contain breaking changes) vs. backwards-compatible (i.e. contain no breaking changes).

Provider systems SHALL publish Service Root URLs for major versions of FHIR APIs in the Spine Directory Service in the following format:

https://[FQDN of FHIR Server]/[FHIR_VERSION_NAME]/[CC_MAJOR_VERSION]/[PROVIDER_ROUTING_SEGMENT]

[FQDN_OF_FHIR_SERVER] is the fully qualified domain name where traffic will be routed to the logical FHIR server for the organisation in question
[FHIR_VERSION_NAME] refers to the textual name identifying the major FHIR version, examples being DSTU2 and STU3. The FHIR Version name SHALL be specified in UPPERCASE characters.
[CC_MAJOR_VERSION] identifies the major version number of the Care Connect specification that the API is built to.
[PROVIDER_ROUTING_SEGMENT] enables providers to differentiate between logical FHIR servers defined by Care Connect capabilities, or other FHIR based APIs. For example, the [PROVIDER_ROUTING_SEGMENT] could be:
- careconnect/metadata for the Foundations capabilities
- careconnect/appointment for the Appointment capabilities
- careconnect/slot for the Slot capabilities
Please note: The Booking Management and Foundations capabilities SHALL have the same [PROVIDER_ROUTING_SEGMENT] value. Other capabilies SHALL have different values.
The Service Root URL SHALL NOT contain a trailing /

Example Service Root URL

The provider SHALL publish the Service Root URL for each capability to Spine Directory Services, for example:

https://provider.nhs.uk/STU3/1/careconnect/structured

Consumer systems are required to construct a Service Root URL containing the SSP URL followed by the FHIR Server Root URL of the providers FHIR server that is suitable for interacting with the SSP service. API provider systems will be unaware of the SSP URL prefix as this will be removed prior to calling the provider API endpoint.

The consumer system would therefore issue a request to the new version of the provider FHIR API to the following URL:

https://[ssp_fqdn]/https://provider.nhs.uk/STU3/1/careconnect/appointment/[FHIR request]

Resource URL

The Resource URL will be in the following format:

VERB [base]/[type]/[id] {?_format=[mime-type]}

Clients and servers constructing URLs SHALL conform to RFC 3986 Section 6 Appendix A which requires percent-encoding for a number of characters that occasionally appear in the URLs (mainly in search parameters).

HTTP verbs

The following HTTP verbs SHALL be supported to allow RESTful API interactions with the various FHIR resources:

GET
POST
PUT
DELETE

Tip: Please see later sections for which HTTP verbs are expected to be available for specific FHIR resources.

Roadmap: In a future version of the FHIR® standard, it is expected that the PATCH verb will also be supported.

Resource types

Care Connect provider systems SHALL support FHIR resource types as detailed within the FHIR Resource Guidance.

Resource ID

This is the logical Id of the resource which is assigned by the server responsible for storing it. The logical identity is unique within the space of all resources of the same type on the same server, is case sensitive and can be up to 64 characters long.

Once assigned, the identity SHALL never change. logical Ids are always opaque, and external systems need not and should not attempt to determine their internal structure.

Important: As stated above and in the FHIR® standard, logical Ids are opaque and other systems should not attempt to determine their structure (or rely on this structure for performing interactions). Furthermore, as they are assigned by each server responsible for storing a resource they are usually implementation specific. For example, NoSQL document stores typically preferring a GUID key (for example, 0b28be67-dfce-4bb3-a6df-0d0c7b5ab4) while a relational database stores typically preferring an integer key (for example, 2345).

For further background, refer to principles of resource identity as described in the FHIR standard

External resource resolution

In line with work being undertaken in other jurisdictions (see the Argonaut Implementation Guide for details) Care Connect provider systems are not expected to resolve full URLs that are external to their environment.

Content types

Servers should support both formal MIME-types for FHIR resources:
- Servers SHALL support JSON: application/fhir+json
- Servers SHOULD support XML: application/fhir+xml
Servers SHALL support the optional _format parameter in order to allow the client to specify the response format by its MIME-type. If both are present, the _format parameter overrides the Accept header value in the request.
Where no Accept header or _format parameter is sent with a request but there is a Content-Type header, such as in a POST request, the server SHALL return the response using the format type within the Content-Type header.
Where no Accept header, _format parameter and no Content-Type header is present, as is possible within a GET request, the server SHALL default to JSON.

Wire format representations

Servers should support two wire formats as ways to represent resources when they are exchanged:

Servers SHALL support JSON
Servers SHOULD support XML

Important: The FHIR standard outlines specific rules for formatting XML and JSON on the wire. It is important to read and understand in full the differences between how XML and JSON are required to be represented.

Providers SHALL ignore unknown extensions and elements in order to foster forwards compatibility and declare this by setting CapabilityStatement.acceptUnknown to ‘both’ in their capability statement.

Systems SHALL declare which format(s) they support in their CapabilityStatement. If a server receives a request for a format that it does not support, it SHALL return an HTTP status code of 415 indicating an Unsupported Media Type.

Warning: It is strongly recommend that suppliers use JSON rather than XML. JSON is a MUST requirement across other NHS Digital interoperability programmes, whereas XML is not.

Transfer encoding

Clients and servers SHALL support the HTTP Transfer-Encoding header with a value of chunked. This indicates that the body of a HTTP response will be returned as an unspecified number of data chunks (without an explicit Content-Length header).

Character encoding

Clients and servers SHALL support the UTF-8 character encoding as outlined in the FHIR standard.

FHIR uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1) defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set the character encoding to UTF-8 using the charset parameter of the MIME-type in the Content-Type header. Requests MAY also specify this charset parameter in the Accept header and/or use the Accept-Charset header.

Where the character encoding is included with the “Content-Type” or “Accept” header there should not be a space between the MIME-type and the character encoding, as per the standard for these headers (RFC 2616).

Content compression

To improve system performances clients/servers SHALL support GZIP compression.

Compression is requested by setting the Accept-Encoding header to gzip.

Consumers should cater for the eventuality of receiving a decompressed response despite requesting a compressed one.

Tip: Applying content compression is key to reducing bandwidth needs and improving battery life for mobile devices.

Inter-version compatibility

Unrecognised search criteria SHALL always be ignored. As search criteria supported in a query are echoed back as part of the search response there is no risk in ignoring unexpected search criteria.

HTTP headers

Proxying headers

Additional HTTP headers SHALL be added into the HTTP request/response for allowing the proxy system to disclose information lost in the proxying process (for example, the originating IP address of a request). Typically, this information is added to proxy forwarding headers as defined in RFC 7239.

Cross-organisation provenance and audit headers

To meet auditing and provenance requirements (which are expected to be closely aligned with the IM1 requirements), clients SHALL provide an oAuth 2.0 Bearer token in the HTTP Authorization header (as outlined in RFC 6749) in the form of a JSON Web Token (JWT) as defined in RFC 7519.

Tip: We are using an open standard (JWT) to provide a container for the provenance and audit data for ease of transport between the consumer and provider systems. It is important to note that these tokens will not be centrally issued and are not signed or encrypted (that is, they are constructed of plain text). There are JWT libraries available for most programming languages simplifying the generation of this data in JWT format.

Refer to Authentication for full details of the JWT claims that SHALL be used for passing audit and provenance details between systems.

Spine Proxy Headers

Clients SHALL add the following Spine proxy headers for audit and security purposes:

Ssp-TraceID - TraceID (generated per request) which identifies the sender’s message/interaction (for example, a GUID/UUID).
Ssp-From - ASID which identifies the sender’s FHIR endpoint.
Ssp-To - ASID which identifies the recipient’s FHIR endpoint.
Ssp-InteractionID - identifies the FHIR interaction that is being performed

The SSP SHALL perform the following checks to authenticate client request:

get the common name (CN) from the TLS session and compare the host name to the declared endpoint
check that the client/sending endpoint has been registered (and accredited) to initiate the given interaction
check that the server/receiving endpoint has been registered (and accredited) to receive/process the given interaction

Caching headers

Providers SHALL use the following HTTP header to ensure that no intermediaries cache responses: Cache-Control: no-store

Integrity headers

Important: Header parameters supporting the integrity of transactions are defined in the Transactional Integrity pages.

Managing resource contention

To facilitate the management of resource contention, servers SHALL always return an ETag header with each resource including the resource’s versionId:

HTTP 200 OK
Date: Sat, 09 Feb 2013 16:09:50 GMT
Last-Modified: Sat, 02 Feb 2013 12:02:47 GMT
ETag: W/"23"
Content-type: application/json+fhir

ETag headers which denote resource version Ids SHALL be prefixed with W/ and enclosed in quotes, for example:

ETag: W/"3141"

Clients SHALL submit update requests with an If-Match header that quotes the ETag from the server.

PUT /Patient/347 HTTP/1.1
If-Match: W/"23"

If the version Id given in the If-Match header does not match, the server returns a 409 Conflict status code instead of updating the resource.

For servers that don’t persist historical versions of a resource (that is, any resource other than the currently available/latest version) then they SHALL operate in line with the guidance provided in the following Hay on FHIR - FHIR versioning with a non-version capable back-end blog post. This is to ensure that Care Connect servers will be compatible with version-aware clients, even though the server itself doesn’t support the retrieval of historical versions.

Managing return errors

To manage return errors, FHIR defines an OperationOutcome resource that can be used to convey specific detailed processable error information. See Error Handling for more information on errors.

Tags: