• API Hub
  • Search loading...

    API Hub

    Explore and Make use of Nationally Defined Messaging APIs

     

    Common API Guidance

    Details of the common request handling pattern(s) across all GP Connect FHIR APIs.

    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 (e.g. 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:

    1. Resource
      1. Resource Identity
      2. Business Identifiers
    2. Domain Resource
      1. Common API
        1. Patient profiled as gpconnect-patient-1.
        2. Practitioner profiled as gpconnect-practitioner-1.
        3. Organization profiled as gpconnect-organization-1.
        4. Location profiled as gpconnect-location-1
      2. Care Record API
        1. Please refer to the Resource Type section of this document.
      3. Bookings API
        1. Schedule profiled as gpconnect-schedule-1
        2. Slot profiled as gpconnect-slot-1
        3. Appointment profiled as gpconnect-appointment-1
      4. Task API
        1. Order profiled as gpconnect-order-1
    3. Resource Metadata
      1. profile
      2. version Id
    4. Bundle
    5. Data Types
      1. Primitive Types
        1. All primitive types SHALL be supported.
      2. Complex Types
        1. The following complex types SHALL be supported.
          1. Identifier
          2. Coding
          3. Codeable Concept
          4. Period
        2. It is expected that further complex types will be introduced as required to model structured data.
    6. Interactions
      1. Instance
        1. READ
        2. UPDATE
        3. DELETE
        4. VREAD
      2. Type Level
        1. CREATE
        2. SEARCH
    7. Search
      1. Search Parameter Types
        1. Date
        2. Token
        3. Reference
      2. Search Prefixes
        1. lt (less than)
        2. le (less or equal to)
        3. gt (great than)
        4. ge (greater or equal to)
        5. ne (not equal to)
      3. Parameters for all resources
        1. _query
        2. _list
      4. Search result parameters
        1. _include can be used internally inside a named _query operation.
        2. _sort can be used internally inside a named _query operation.
      5. Chained parameters (limited to patient identifier only)
    8. Operations
      1. Implementation Defined 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:

    1. Operations
      1. Validate a resource
      2. Meta operations
      3. Generate a document
      4. Process message
      5. Find a functional list
      6. ConceptMap operations
      7. Closure Table Maintenance
      8. Fetch records
      9. Questionnaire operations
      10. Terminology operations
    2. Interactions
      1. Instance
        1. HISTORY
      2. Type Level
        1. HISTORY
      3. Whole System
        1. BATCH TRANSACTION
        2. HISTORY
        3. SEARCH
      4. Conditional Interactions
        1. CREATE
        2. UPDATE
        3. DELETE
    3. Search
      1. Parameter Types
        1. Number
        2. String
        3. Quantity
        4. Composite
        5. URL
      2. Parameters for all resources
        1. _language
        2. _lastUpdate
        3. _tag
        4. _profile
        5. _security
        6. _text
        7. _content
        8. _filter
      3. Search result parameters
        1. _revinclude
        2. _count
        3. _summary
        4. _elements
        5. _contained
        6. _containedType
      4. Chained parameters (limited to patient identifier only)
      5. Paging / Page Count
    4. Resource Metadata
      1. lastUpdated
      2. security
      3. tag

    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.

    Endpoint Resolution

    Clients SHALL perform a sequence of query operations against existing Spine services to enable FHIR endpoint resolution.

    1. Clients SHALL perform (or have previously performed) a PDS lookup for a patient.
      1. Using the PDS results the client SHALL determine the patient’s primary GP organisation.
    2. Clients SHALL perform (or have previously performed) a SDS lookup using the ODS code of the patient’s primary GP organisation.
      1. Using the SDS results the client SHALL determine the Principal GP system responsible for hosting the most up to date GP care record.
        1. EMIS Health
        2. INPS
        3. Micotest
        4. TPP
    3. Clients SHALL construct a FHIR Service Root URL suitable for access to a GP vendor’s FHIR server. For GP Connect access to the Principal GP systems will be via the Spine Security Proxy and as such the URL will need to be pre-pended with a Proxy Service Root URL.

    Security

    TLS SHALL 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 (e.g. 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 SHALL authenticate using TLS Mutual Authentication (MA) utilising client certificates provided by the NHS Digital for this purpose.

    System Conformance

    Servers SHALL provide a read-only FHIR Conformance resource that identifies all of the profiles and operations that the server supports for each resource type.

    A servers conformance statement SHALL 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 SHALL, 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 (i.e. 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 SHALL be aligned with the GP 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]/[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 being DSTU2 and STU3. The FHIR Version name SHALL 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 (e.g. via a load balancer). If included, this optional provider routing segment SHALL be static across all the provider’s GP Connect API endpoints.

    • The Service Root URL SHALL NOT contain a trailing /

    Example Service Root URL

    The provider SHALL publish the Service Rot 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 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

    Resource Type

    GP Connect provider systems SHALL support FHIR resource types as profiled within the GP Connect FHIR Resource Definitions.

    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.

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

    External Resource Resolution

    Inline 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 SHALL support both formal MIME-types for FHIR resources:

    • XML: application/xml+fhir
    • JSON: application/json+fhir

    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.

    Servers SHALL 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 SHALL support two wire formats as ways to represent resources when they are exchanged:

    Consumers SHALL 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 SHALL 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 SHALL return a http status code of 415 indicating an Unsupported Media Type.

    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 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.

    Content Compression

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

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

    Inter-version Compatibility

    Unrecognized 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 the purpose of allowing the proxy system to disclose information lost in the proxying process (e.g. 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 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.

    Refer to Integration - Cross Organisation Audit & Provenance for full details of the JWT claims that SHALL be used for passing audit and provenance details between systems.

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

    • Ssp-TraceID - TraceID (generated per request) which identifiers the sender’s message/interaction (i.e. 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.1

    1 please refer to the Development - FHIR API Guidance - Operation Guidance for full details.

    The Spine Security Proxy (SSP) SHALL 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 SHALL use the following HTTP Header to ensure that no intermediaries cache responses: Cache-Control: no-store

    Managing Return Content

    Provider SHALL maintain resource state inline 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.

    Diagram of reflection of state

    Severs SHALL default to the return=representation behaviour (i.e. 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 SHALL 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 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 server’s that don’t persist historical versions of a resource (i.e. 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 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 (i.e. user’s language, region and any special variant preferences that the user may want to see in their user interface) of a systems SHALL NOT effect the FHIR on the wire representation of any data types (especially date-time and number formats).

    Certain aspects of Primitive Data Type respresentation warrant further consideration and SHALL be taken into consideration when designing and constructing FHIR resources.

    For example:

    • Leading 0 digits are not allowed.
    • Strings SHALL 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 (e.g. just year or year + month).
    • Precision of the decimal value has signficance.
    • Primitive types other than string SHALL NOT have leading or trailing whitespace.
    • 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 (i.e. its ability to ‘follow the links’ to other resources).

    Resource references SHALL 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 SHALL be formatted inline with Common User Interface (CUI) guidance where such guidance exists (e.g. patient name).

    Resource Display Format
    Patient patient.name
    Practitioner practitioner.name
    Organization organization.name

    Resource Metadata

    Servers SHALL provide the profile metadata for each resource, asserting that the content conforms to one of the GP Connect resource profiles.

    Servers SHALL provide the version Id metadata for each item. This SHALL change each time the content of the resource changes.

    Consumer creating or amending a resource SHALL 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 SHALL 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:

    • SHALL 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 SHALL validate the existence of any referenced resources when creating or updating a resource. For example, a Slot reference (e.g. 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 upto date details on how FHIR resources can be validated.

    Servers SHALL provide a read interaction for every resource it accepts update interactions on.

    Consumers SHALL 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 SHALL 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 SHALL 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 SHALL 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 SHALL 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 SHALL 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 SHALL 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 SHALL have an id element with a value that is the [id].

    Servers SHALL 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
    Tasks Order

    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
    

    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 SHALL be utilised.

    POST [base]/[resourcetype]
    

    When the server creates a new resource and returns a 201 Created HTTP status code, it SHALL 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
    Tasks Order

    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 SHALL 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 SHALL be returned.

    Capability Resource(s) Field(s)
    Foundations    
    Access Record    
    Appointments Appointment reason, description, comment
    Tasks    

    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 SHALL be utilised.

    DELETE [base]/[resourcetype]/[id]
    
    Capability Resource(s)
    Foundations  
    Access Record  
    Appointments  
    Tasks  

    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 it’s operation names with a short prefix (e.g. 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 SHALL 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 SHALL 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 SHALL 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>
    

    Servers SHALL 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>
    

    All content is available under the Open Government Licence v3.0, except where otherwise stated