Purpose

This implementation guide is intended for use by software developers looking to build a conformant CDS 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’ in this implementation guide are to be interpreted as described in RFC 2119.

Resources

Key FHIR resources have been included in this implementation guide. Any referenced resources in the interactions or key resources which are not explicitly included in this implementation guide will be the HL7 STU3 versions of these resources, following all constraints of that version.

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, 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 GET /fhir/Patient/1.

The FHIR RESTful API style guide defines the following URL conventions which are used in this specification:

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

Resource URL

The Resource URL will be in the following format:

Clients and servers constructing URLs MUST 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 MUST be supported to allow RESTful API interactions with the various FHIR resources:

• GET
• POST

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 MUST never change; logical Ids are always opaque, and external systems need not and SHOULD NOT attempt to determine their internal structure.

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

Referenced Resources

Resources will commonly be referred to as part of other resources (e.g. a GuidanceResponse may refer to a Questionnaire). FHIR accepts passing of resources either by reference, or by value (by including in a Bundle). This guide is agnostic about passing resourferences by reference or by value within a Bundle. FHIR also accepts passing of resource by value as contained resources - this approach is NOT recommended, but is not explicitly excluded.

The choice of whether to pass resources by reference or by value (as part of Bundle) is left to the provider server. The consumer MUST be able to accept either. It will be dependent on the implementation generally as to which option is more appropriate. In general, passing by value reduces the number of calls between the systems, while passing by reference reduces the size of each communication, and may be more appropriate where resources are referenced in different interactions, but do not change between those interactions (e.g. Questionnaire).

Content types for consumer and provider systems

Each of the systems in scope of the CDS API act as both provider and consumer in different interactions:

Consuming systems

• A consuming system MUST support both formal MIME-types for FHIR resources:
  • XML: application/fhir+xml
  • JSON: application/fhir+json
• A consuming system MUST also gracefully handle generic XML or JSON MIME types:
  • XML: application/xml
  • JSON: application/json
  • JSON: text/json
• A consuming system MUST 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.
• If neither the Accept header nor the _format parameter are supplied by the client system, the provider and consuming systems MUST return data in the default format of application/fhir+json.

Providing systems

• A provider system MUST support one of the formal MIME-types for FHIR resources:
  • XML: application/fhir+xml
  • JSON: application/fhir+json
• A provider system MUST also gracefully handle generic MIME types for either XML or JSON:
  • XML: application/xml
  • JSON: application/json
  • JSON: text/json

Cardinality

All attributes defined in FHIR have cardinality as part of their definition - a minimum number of required appearances and a maximum number. These numbers specify the number of times the attribute may appear in any instance of the resource type. This specification only defines the following cardinalities: 1..1, 0..1, 1..* and 0..*. The following table illustrates the cardinality rules:

Resources created violating the business rules may generate an HTTP 400 Error INVALID_RESOURCE.