Purpose
This document is intended for use by software developers looking to build a conformant GP Connect API interface utilising the FHIR® standard.
Notational conventions
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
FHIR implementation guidance
The purpose of the implementation guide is to describe adaptations of the base FHIR specification specific for GP Connect First of Type (FoT) implementations. It therefore focuses mainly on any additional constraints and specialisations from the base specification that apply to GP Connect. The complete specification therefore comprises the base FHIR specification plus the constraints and specialisations described herein. Where there is a conflict between the base specification and this document, this document shall take precedence.
FHIR overview
As outlined on the official HL7® FHIR website:
FHIR (Fast Health Interoperability Resources) is designed to enable information exchange to support the provision of healthcare in a wide variety of settings. The specification builds on and adapts modern, widely used RESTful practices to enable the provision of integrated healthcare across a wide range of teams and organizations.
FHIR timelines
FHIR is currently a draft standard and as such is expected to evolve and develop over time. As such the NHS Digital expects FHIR clients and servers (developed as part of GP Connect) to be maintained and uplifted to newer versions of the FHIR® standard as they become available and are staged into the GP Connect programme.
A pre-release version of FHIR (expected to be the basis of STU3) has been published as the May 2016 release. The FHIR community is expecting the finalised STU3 release to be made available in late 2016/early 2017.
When a new release of the FHIR standard has been published for use NHS Digital will carry out an impact assessment of all FHIR resources used by the GP Connect API project to determine the impact of transitioning to the new FHIR release. Following this assessment, the FHIR Resource library will be updated to include resources using this new release. NHS Digital will work with Consumers and Providers throughout this transition phase and are expected to maintain both versions of the FHIR release until it has been agreed that the old version can be deprecated.
FHIR implementations
The Health Level Seven (HL7®) International standards body maintains a list of open source FHIR implementations on their Wiki. Currently five FHIR server implementations and a number of client libraries are available as open source software. These are written in a variety of popular programming languages (for example, Java, C#.NET, JavaScript and Python).
FHIR in scope
To help API implementers deal with the FHIR learning curve NHS Digital has worked to constrain the scope of the FHIR® standard that is expected to be implemented in the first tranche of development work as follows:
- resource
- domain resource
- common API
- Patient profiled as gpconnect-patient-1
- Practitioner profiled as gpconnect-practitioner-1
- Organization profiled as gpconnect-organization-1
- Location profiled as gpconnect-location-1
- care record API
- please refer to the Resource Type section of this document
- bookings API
- Schedule profiled as gpconnect-schedule-1
- Slot profiled as gpconnect-slot-1
- Appointment profiled as gpconnect-appointment-1
- common API
- resource metadata
- bundle
- data types
- primitive types
- all primitive types MUST be supported.
- complex types
- the following complex types MUST be supported.
- it is expected that further complex types will be introduced as required to model structured data.
- primitive types
- interactions
- search
- search parameter types
- search prefixes
- lt (less than)
- le (less or equal to)
- gt (great than)
- ge (greater or equal to)
- ne (not equal to)
- parameters for all resources
- search result parameters
- chained parameters (limited to patient identifier only)
- operations
FHIR out of scope
GP Connect provider systems are not expected to implement the following aspects of the FHIR® standard under the scope of the first tranche of development work:
- operations
- validate a resource
- meta operations
- generate a document
- process message
- find a functional list
- conceptMap operations
- closure table maintenance
- fetch records
- questionnaire operations
- terminology operations
- interactions
- instance
- HISTORY
- type level
- HISTORY
- whole system
- BATCH TRANSACTION
- HISTORY
- SEARCH
- conditional interactions
- CREATE
- UPDATE
- DELETE
- instance
- search
- parameter types
- Number
- String
- Quantity
- Composite
- URL
- parameters for all resources
- _language
- _lastUpdate
- _tag
- _profile
- _security
- _text
- _content
- _filter
- search result parameters
- _revinclude
- _count
- _summary
- _elements
- _contained
- _containedType
- chained parameters (limited to patient identifier only)
- paging / page count
- parameter types
- resource metadata
- lastUpdated
- security
- tag
Internet standards
Clients and servers MUST 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 MUST 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 MUST be via TLS/HTTPS as defined in RFC 5246 and RFC 6176.
- HTTP Strict Transport Security (HSTS) as defined in RFC 6797 MUST be employed to protect against protocol downgrade attacks and cookie hijacking.
Security
TLS MUST be used for all data exchange. The TLS communications are established prior to any HTTP command/response, so the whole FHIR interaction is protected by the TLS communications.
The security of the endpoints of the TLS communications must be risk-managed, so as to prevent inappropriate risks (for example, audit logging of the GET parameters into an unprotected audit log).
Authentication
The FHIR® standard specifies that users/clients/servers MAY be authenticated in any way desired. However, for web-centric use, oAuth (RFC 6749) is recommended but not mandated by the FHIR® standard.
For the purpose of GP Connect FoT clients and servers MUST authenticate using TLS Mutual Authentication (MA) utilising client certificates provided by the NHS Digital for this purpose.
System conformance
Servers MUST provide a read-only FHIR Conformance resource that identifies all of the profiles and operations that the server supports for each resource type.
A server’s conformance statement MUST be available using the following conformance interactions:
GET [base]/metadata {?_format=[mime-type]}
Refer to Foundations - Get The FHIR Conformance Profile for an example GP Connect FHIR conformance profile.
Resource conformance
To help a consumer find the correct set of reports for a use-case, a provider of resources MUST, for any profile declared in Conformance.profile
mark resources with profile assertions documenting the profile(s) they conform to. A provider of resources SHOULD also ensure that any resource instance that would reasonably be expected to conform to the declared profiles SHOULD be published in this form.
GP Connect API conformance
GP Connect comprises a number of RESTful API bundles. Each API bundle is intended to support sets of related use cases, for example the Appointment API bundle supports viewing, booking and cancelling GP appointments in a number of scenarios.
Individual API bundles MAY be provided independently of each other. GP Connect conformance MAY be claimed in relation to one or more API bundles. A provider claiming to provide an API bundle must be fully conformant (that is, implement all of the resource profiles and interactions for the API bundle as specified in this document and all of the general requirements described herein).
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 address where all of the resources defined by this interface are found.
The Service root URL is the [base]
portion of all FHIR APIs.
Service root URL versioning
Service root URLs MUST be aligned with the GP Connect specification they were built against, specifically the major version number MUST be present in the server’s Service root URL to provide a clear distinction between API versions that are incompatible (that is, contain breaking changes) vs. backwards-compatible (that is, contain no breaking changes).
Provider systems MUST publish Service root URLs for major versions of FHIR APIs in the Spine Directory Service in the following format:
https://[FQDN of FHIR Server]/[ODS_CODE]/[FHIR_VERSION_NAME]/[GPC_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 -
[ODS_CODE]
is the Organisation Data Service code which uniquely identifies the GP Practice organisation -
[FHIR_VERSION_NAME]
refers to the textual name identifying the major FHIR version, examples beingDSTU2
andSTU3
. The FHIR Version name MUST be specified in UPPERCASE characters. -
[GPC_MAJOR_VERSION]
identifies the major version number of the GP Connect specification that the API is built to. -
[PROVIDER_ROUTING_SEGMENT]
enables providers to differentiate between GP Connect and non-GP Connect requests (for example, via a load balancer). If included, this optional provider routing segment MUST be static across all the provider’s GP Connect API endpoints. -
The Service root URL MUST NOT contain a trailing
/
Example Service root URL
The provider MUST publish the Service Root URL to Spine Directory Services, for example:
https://provider.nhs.uk/GP0001/DSTU2/0/gpconnect
Consumer systems are required to construct a Service root URL containing the SSP URL followed by the FHIR Server root URL of the logical practice 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/GP0001/DSTU2/0/gpconnect
Resource URL
VERB [base]/[type]/[id] {?_format=[mime-type]}
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
- PUT
- DELETE
Resource type
GP Connect provider systems MUST support FHIR resource types as profiled within the GP Connect FHIR Resources.
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.
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 prefer a GUID key (for example, 0b28be67-dfce-4bb3-a6df-0d0c7b5ab4) whilst relational database stores typically prefer an integer key (such as 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) GP Connect provider systems are not expected to resolve full URLs that are external to their environment.
Content types
Servers MUST support both formal MIME-types for FHIR resources:
- XML:
application/xml+fhir
- JSON:
application/json+fhir
Servers 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.
Servers MUST prefer the encoding specified by the Content-Type
header if no explicit Accept
header has been provided by a client application.
Wire format representations
Servers MUST support two wire formats as ways to represent resources when they are exchanged:
Consumers MUST ignore unknown extensions and elements in order to foster forwards compatibility and declare this by setting Conformance.acceptUnknown to ‘both’ in their conformance profile.
Systems MUST declare which format(s) they support in their Conformance Statement. If a server receives a request for a format that it does not support it MUST return an HTTP status code of 415
indicating an Unsupported Media Type
.
Transfer encoding
Clients and servers MUST support the HTTP Transfer-Encoding
header with a value of chunked
. This indicates that the body of an HTTP response will be returned as an unspecified number of data chunks (without an explicit Content-Length
header).
Character encoding
Clients and servers MUST 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 ofISO-8859-1
, requests and responses MUST explicitly set the character encoding toUTF-8
using thecharset
parameter of the MIME-type in theContent-Type
header. Requests MAY also specify this charset parameter in theAccept
header and/or use theAccept-Charset
header.
Content compression
To improve system performances clients/servers MUST support GZIP compression.
Compression is requested by setting the Accept-Encoding
header to gzip
.
Inter-version Compatibility
Unrecognized search criteria MUST 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 MUST be added into the HTTP request/response for the purpose of 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 & audit headers
In order to meet auditing and provenance requirements (which are expected to be closely aligned with the IM1 requirements), clients MUST 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.
Refer to Integration - Cross Organisation Audit & Provenance for full details of the JWT claims that MUST be used for passing audit and provenance details between systems.
Clients MUST add the following Spine proxy headers for audit and security purposes:
Ssp-TraceID
- TraceID (generated per request) which identifiers the sender’s message/interaction (that is, a GUID/UUID)Ssp-From
- ASID which identifies the sender’s FHIR endpointSsp-To
- ASID which identifies the recipient’s FHIR endpointSsp-InteractionID
- identifies the FHIR interaction that is being performed 1
1 please refer to the Development - FHIR API Guidance - Operation Guidance for full details.
The Spine Security Proxy (SSP) MUST perform the following checks to authenticate client request:
- get the 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 MUST use the following HTTP Header to ensure that no intermediaries cache responses: Cache-Control: no-store
Managing return content
Provider MUST maintain resource state in line with the underlying system, including the state of any associated resources.
For example:
If the practitioner associated with a schedule is changed on the providers system, such as when a Locum is standing in for a regular doctor, this should be reflected in all associated resources to that schedule. The diagram below shows the expected change to the appointment resources for this scenario.
When the appointment is booked, the appointment resource is associated with a slot resource and references the practitioner resource associated with the schedule in which the slot resides. If the schedule is then updated within the provider system to reflect the change of practitioner from the original doctor to a Locum doctor then the practitioner reference with the schedule will be updated. If a consumer then performs a read of the appointment the returned appointment resource should reflected the updated practitioner on the schedule.
Severs MUST default to the return=representation
behaviour (that is, returning the entire resource) for interactions that create or update resources.
Servers SHOULD honour a return=minimal
or return=representation
preference indicated in the Prefer
request header, if present.
Managing resource contention
Servers MUST always return an ETag
header with each resource including the resources 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 Id
s MUST be prefixed with W/
and enclosed in quotes, for example:
ETag: W/"3141"
Clients MUST 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 MUST 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 GP 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
FHIR defines an OperationOutcome resource that can be used to convey specific detailed processable error information. An OperationOutcome
MAY be returned with any HTTP 4xx
or 5xx
response, but is not always required.
FHIR resources
Resource data types
The FHIR specification defines a set of data types that are used for the resource elements.
The user locale (that is, user’s language, region and any special variant preferences that the user may want to see in their user interface) of a systems MUST NOT effect the FHIR on the wire representation of any data types (especially date-time and number formats).
Certain aspects of Primitive Data Type representation warrant further consideration and MUST be taken into consideration when designing and constructing FHIR resources.
For example:
- leading 0 digits are not allowed
- strings MUST NOT exceed 1MB in size
- URIs are case sensitive
- UUID values (urn:uuid:53fefa32-fcbb-4ff8-8a92-55ee120877b7) use all lowercase
- dates have no time zone
- dates can be partial dates (for example, just year or year + month)
- precision of the decimal value has significance
- primitive types other than string MUST NOT have leading or trailing white-space
- use of null and empty / zero length values in XML and JSON representations
Resource narrative
The FHIR resource narrative is not currently expected to be populated.
Resource references
The FHIR resource model includes references from one resource to another.
A reference can be either:
- a relative or absolute URL to a resource managed by the same resource server (a local reference), or
- an absolute URL to a resource managed by another resource server (a remote reference)
A provider’s ability to process a request relating to a resource may depend on its ability to use one or more resource references that the resource contains (that is, its ability to ‘follow the links’ to other resources).
Resource references MUST include a short human-readable display
field for identification of the resource that is being referenced which can be used for display purposes without needing to pull the entire referenced resource. The short human-readable display
field MUST be formatted in line with Common User Interface (CUI) guidance where such guidance exists (for example, patient name).
Resource | Display Format |
---|---|
Patient |
patient.name |
Practitioner |
practitioner.name |
Organization |
organization.name |
Resource metadata
Servers MUST provide the profile
metadata for each resource, asserting that the content conforms to one of the GP Connect resource profiles.
Servers MUST provide the version Id
metadata for each item. This MUST change each time the content of the resource changes.
Consumer creating or amending a resource MUST provide the profile
metadata details within the sent resource. The profile
metadata should be checked for by the Provider to ensure predictable process and for forward compatibility when a server can handle multiple profiles for the same type of resource.
Clients MUST utilise the version Id
when performing updates to allow management of resource contention and to protect against Lost Updates.
Resource transactions
When performing an update or create interaction, servers:
- MUST validate the content against valid profiles and business rules before creating/updating the resource
- MAY apply business rules that alter the content
- MAY merge updated content with existing content
Servers MUST validate the existence of any referenced resources when creating or updating a resource. For example, a Slot
reference (for example, Slot/D497DB00-99AA-11E5-A837-0800200C9A66
) used when creating a new Appointment
would be checked for existence on the server and an error returned (and the create interaction aborted) if the slot does not exist.
Refer to the GitHub hosted GP Connect FHIR Repository for the published FHIR profiles.
Refer to the HL7® FHIR® Validator page for the most up to date details on how FHIR resources can be validated.
Servers MUST provide a read interaction for every resource it accepts update interactions on.
Consumers MUST follow the pattern described in the Transactional Integrity section of the base FHIR specification, built on top of version-aware updates, for updating resources.
FHIR resource interactions
Requests
Servers MUST be able to consume and process the following requests for GP Connect FoT.
Interaction | Path | Request Verb | Request Content-Type | Body | Prefer | Conditional |
---|---|---|---|---|---|---|
read |
/[type]/[id] |
GET |
N/A | N/A | N/A | ETag |
update |
/[type]/[id] |
PUT |
R | Resource | O | If-Match |
delete |
/[type]/[id] |
DELETE |
N/A | N/A | N/A | N/A |
create |
/[type] |
POST |
R | Resource | O | N/A |
search |
/[type]? |
GET |
N/A | N/A | N/A | N/A |
(operation) |
/[type]/$[name] /[type]/[id]/$[name] |
POST GET |
R application/x-www-form-urlencoded |
Parameters form data |
N/A | N/A |
N/A = not present, R = Required, O = Optional
Responses
Servers MUST be expected to produce the following responses for GP Connect FoT.
Interaction | Response Content-Type | Body | Location | Content-Location | Versioning | Status Codes |
---|---|---|---|---|---|---|
read |
R | R: Resource | N/A | R | ETag |
200 , 404 , 410 |
update |
R | R: Resource | N/A | R | ETag |
200 , 201 , 400 , 404 405 , 409 , 412 , 422 |
delete |
R | R: Operation Outcome | N/A | N/A | N/A | 200 , 204 , 404 , 405 , 409 , 412 |
create |
R | R: Resource | R | R | ETag |
201 , 400 , 404 405 , 422 |
search |
R | R: Bundle | N/A | N/A | N/A | 200 , 403 |
(operation) |
R | R: Parameters/Resource | N/A | N/A | N/A | 200 , 400 , 403 , 404 , 422 |
N/A = not present, R = Required, O = Optional
Response codes
Servers MUST produce the following main HTTP status codes.
HTTP Status Code | Description |
---|---|
200 |
OK |
201 |
Created |
400 |
Bad Request |
401 |
Unauthorized |
403 |
Forbidden |
404 |
Not Found |
405 |
Method Not Allowed |
409 |
Conflict |
410 |
Gone |
412 |
Precondition Failed |
415 |
Unsupported Media Type |
422 |
Unprocessable Entity |
500 |
Internal Server Error |
501 |
Not Implemented |
Rejecting updates
OperationOutcome MAY be returned with any HTTP 4xx
or 5xx
response, but is not required - many of these errors may be generated by generic server frameworks underlying a FHIR server.
Servers are permitted to reject update interactions because of integrity concerns or other business rules, and return HTTP status codes accordingly (usually a 422
).
As outlined in the FHIR specification, any of these errors SHOULD be accompanied by an OperationOutcome resource that provides additional detail concerning the issue.
Refer to FHIR guidance - error handling for full details of error codes that MUST be used when returning an operation outcome error.
Compartment based access
VERB [base]/[compartment_type]/[id]/[type]{?_format=[mime-type]}
Each resource type may belong to one or more logical compartments. A compartment is a logical grouping of resources which share a common property.
Servers MUST support the Patient
compartment for Appointment
access.
The patient compartment includes any resources where the subject
of the resource is the patient.
For example, to retrieve a list of all of a patient’s appointments, use the URL:
GET [base]/Patient/[id]/Appointment
Servers MUST support searching within this compartment by start
and end
date/time, for example:
GET [base]/Patient/[id]/Appointment?start=[{search_prefix}start_date]{&start=[{search_prefix}end_date]}
Example:
Read Resource
GET [base]/[type]/[id]{?_format=[mime-type]}
The returned resource MUST have an id
element with a value that is the [id].
Servers MUST return an ETag
header with the version Id
of the resource.
Available for resources
Capability | Resource(s) |
---|---|
Foundations | Patient , Practitioner , Organization |
Access Record | TBC |
Appointments | Appointment , Schedule , Slot , Location |
Retrieving a patient resource by logical Id
Request
GET [base]/Patient/[id]
For example:
GET [base]/Patient/1A6E1B1C-6340-4663-926C-9CD1306EAAF8?_format=application/xml+fhir
_format
parameter. This could also have been specified using the HTTP Accept Header mechanism.Response
<Patient xmlns="http://hl7.org/fhir">
<id value="1A6E1B1C-6340-4663-926C-9CD1306EAAF8" />
<meta>
<profile value="http://fhir.nhs.net/StructureDefinition/gpconnect-patient-1" />
</meta>
<identifier>
<system value="http://fhir.nhs.net/Id/nhs-number" />
<value value="9900002831" />
</identifier>
<identifier>
<type>
<coding>
<system value="http://fhir.nhs.net/ValueSet/gpconnect-patient-identifier-type-1" />
<code value="Local" />
<display value="Local identifier" />
</coding>
</type>
<system value="http://fhir.nhs.net/Id/local-identifier" />
<value value="L12345" />
</identifier>
<name>
<use value="usual" />
<family value="Taylor" />
<given value="Sally" />
<prefix value="Mrs" />
</name>
<birthDate value="1947-06-09" />
<address>
<use value="home" />
<type value="both" />
<line value="42, Grove Street" />
<city value="Overtown" />
<district value="West Yorkshire" />
<postalCode value="LS21 1PF" />
</address>
</Patient>
Create resource
To create a new resource a RESTful POST operation with a request body MUST be utilised.
POST [base]/[resourcetype]
When the server creates a new resource and returns a 201
Created HTTP status code, it MUST also return a Location
header which contains the new logical Id
and version Id
of the created resource.
Location: [base]/[type]/[id]/_history/[vid]
[id] and [vid] are the newly created logical Id
and version Id
for the resource version. An ETag
header with the version Id
and a Last-Modified
header will also be included in the response.
Available for resources
Capability | Resource(s) |
---|---|
Foundations | |
Access Record | |
Appointments | Appointment |
Create example: book an appointment for a patient
Request
POST [base]/Appointment
Request body
<Appointment>
</Appointment>
Response
<Appointment>
</Appointment>
Update resource
To update an existing resource, a RESTful PUT operation with a request body MUST be utilised.
PUT [base]/[resourcetype]/[id]
The PUT operation will only be used to update existing resources, if the specified resource within the URL does not exist on the provider system an error MUST be returned.
Capability | Resource(s) | Field(s) |
---|---|---|
Foundations | ||
Access Record | ||
Appointments | Appointment |
reason, description, comment |
Update example: modify the appointment reason for a patient as their condition has changed
Request
PUT [base]/Appointment/2A6FFB1C-5540-1613-926C-7DD1306EBBF8
Request body
<Appointment>
</Appointment>
Response
<Appointment>
</Appointment>
Delete resource
To delete an existing resource, a RESTful DELETE operation with no request body MUST be utilised.
DELETE [base]/[resourcetype]/[id]
Capability | Resource(s) |
---|---|
Foundations | |
Access Record | |
Appointments |
Operations
Operations are used (a) where the server needs to play an active role in formulating the content of the response, not merely return existing information, or (b) where the intended purpose is to cause side effects such as the modification of existing resources, or creation of new resources.
As outlined in the Extend and Restricting the API section of the FHIR® standard, the NHS Digital has decided to prefix its operation names with a short prefix (for example, gpc
) followed by a “.” to reduce the likelihood of name conflicts.
Search Resources
A simple search is executed by performing a GET
request optionally accompanied by zero or more name-value URL encoded parameters:
GET [base]/[resourcetype]?name=value&...
In order to enable searching by date/time range, servers MUST support the following prefixes as defined in the base FHIR specification for date parameters: eq, gt, lt, ge, le.
To search for all the appointments for a patient that occurred over a 2-year period:
GET [base]/Patient/1A6E1B1C-6340-4663-926C-9CD1306EAAF8/Appointment?start=ge2014-01-01&start=le2015-12-31
Chained parameters
Servers MUST support searching by a chained Patient
identifier parameter for references to Patient
resources that conform to the GP-Patient
profile (and therefore have an NHS Number identifier). For example:
GET [base]/AllergyIntolerance?patient.identifier=http://fhir.nhs.net/Id/nhs-number|1234569876
Search example: search for a patient resource by business Id
Request
GET [base]/Patient?identifier=http://fhir.nhs.net/Id/nhs-number|9900002831
If a Patient resource for NHS number 9900002831 exists then the server MUST return a Bundle containing all Patient resources with the specified NHS number identifier.
Response
<Bundle>
<Patient xmlns="http://hl7.org/fhir">
<id value="1A6E1B1C-6340-4663-926C-9CD1306EAAF8" />
<meta>
<profile value="http://fhir.nhs.net/StructureDefinition/gpconnect-patient-1" />
</meta>
<identifier>
<system value="http://fhir.nhs.net/Id/nhs-number" />
<value value="9900002831" />
</identifier>
<name>
<use value="usual" />
<family value="Smith" />
<given value="Mike" />
<prefix value="Mr" />
</name>
<birthDate value="1977-01-09" />
<address>
<use value="home" />
<type value="both" />
<line value="2, The Green" />
<city value="Harrogate" />
<district value="Yorkshire" />
<postalCode value="HG1 4AF" />
</address>
</Patient>
</Bundle>
Advanced search
Servers MUST implement the _query
search parameter to enable custom named search profiles to be defined and used which describe a specific query operation.
GET [base]/[resourcetype]?_query=[query_name]&name=value&...
Servers SHOULD implement the standard search equivalent of the advanced custom named search for queries defined under the GP Connect FoT.
Request
GET [base]/Schedule?_query=getschedule&date=ge2016-05-12&date=le2016-05-26
Response
<Bundle xmlns="http://hl7.org/fhir">
<type value="searchset"/>
</Bundle>