NHS Booking and Referral Standard

BaRS API Spec Change Log

This page will list all updates to the BaRS API Specification.

- Indicates a change inspired by provider or supplier feedback.

Each section will reference only changes for its specific version.

Global

Change Log

Change	BaRS Version	Description	Impact
- Additional patient demographic parameters added to GET /Appointment	1.9.0	Patient demographic parameters (Name, Date of Birth and Address) added to support patient lookup for cancellation and update workflows.	Addition
- Additional patient demographic parameters added to GET /ServiceRequest	1.9.0	Patient demographic parameters (Name, Date of Birth and Address) added to support patient lookup for cancellation and update workflows.	Addition
Fixed incorrect character display on GET /Slot description	1.9.0	Character display for a double quote was illegible.	correction
Removal of use-context HTTP header	1.8.2	Restricted the use of the use-context header to non-write operations	correction
Improvments to header documentation	1.8.2	Added better explanations for most of the headers needed	Addition
Addition of the use-context HTTP header	1.8.1	A new header to assist in audting and logging	Addition
- The DoS ID examples updated to https	1.8.0	The https://fhir.nhs.uk/Id/dos-service-id examples now correcly show as https.	correction
	1.8.0	The example deviceName element in NHSD-Requesting-Software now shows correctly as an Object as defined by the schema	correction
Resilience to Endpoint Catalogue	1.5.0	The proxies mechanism for obtaining Target Endpoints has been updated to allow for more resilience in the event of a dependency failure.	correction
Modifications to allow for future enhancements	1.5.0	The proxy has been modified to allow further endpoints and resources more easily in the future.	correction
Publication of the 1.2.0 Specification	1.5.0	1.2.0 Specification (alpha) launched	Addition
Improvement to DocumentReference Schema	1.5.0	the DocumentReference Schemas have been flattend for easier consumption	correction
- Corrections to example references containing http.	1.5.0	Several references to http://fhir.nhs.uk have been corrected to "https".	correction

Previous Releases

1.3.0

Change Log

in BaRS 1.9.0

Change	Description	Impact
- Additional patient demographic parameters added to GET /Appointment	1.9.0	Patient demographic parameters (Name, Date of Birth and Address) added to support patient lookup for cancellation and update workflows.	Addition
- Additional patient demographic parameters added to GET /ServiceRequest	1.9.0	Patient demographic parameters (Name, Date of Birth and Address) added to support patient lookup for cancellation and update workflows.	Addition
Fixed incorrect character display on GET /Slot description	1.9.0	Character display for a double quote was illegible.	correction

1.2.0

Change Log

in BaRS 1.8.1

Change	Description	Impact
Addition of the use-context HTTP header	A new header to assist in audting and logging	Addition

In BaRS 1.8.0

Change	Description	Impact
- The DoS ID examples updated to https	The https://fhir.nhs.uk/Id/dos-service-id\|111111111 examples now correcly show as https.	correction
- DeviceName Element Correction	The example deviceName element in NHSD-Requesting-Software now shows correctly as an Object as defined by the schema	correction

Initial release In BaRS 1.5.0

BaRS 1.5.0

Change	Description	Impact
Publication of the 1.2.0 Specification along side 1.0.0 and 1.1.0	1.2.0 Specification (alpha) launched	Addition
Additions of Endpoint Catalogue Endpoints	Additional header item and requirement changes for existing headers	Addition
Additional functionality added for Appointment	Additional HTTP Verbs added for /Appointment (PUT, PATCH, POST, DELETE)	Addition
Additional functionality added for ServiceRequest	Additional HTTP Verbs added for /ServiceRequest (PUT, PATCH, POST, DELETE)	Addition
CapabilityStatement updated to reflect changes	The capability statement has been ammended to reflect new capabilities	Addition
Improvement to DocumentReference Schema	the DocumentReference Schemas have been flattend for easier consumption	correction

This Section will list all updates to the BaRS API Specification within the 1.2.0 minor release, published for BaRS 1.5.0. Note this version is still in development.

Publication of the 1.2.0 API Specification (in development)

The API Spec landing page will now have the an additional version to select to view. At present this will present 1.0.0, 1.1.0 and 1.2.0, with links to each specification. 1.1 and 1.2.0 are currently in development.

Endpoint Catalogue

EndpointCatalogue related Endpoints have been added to the specification in preparation for future use cases.

The following endpoints are now available in the 1.2.0 specification. These endpoints will be used in future use cases and future iterations of current use cases.

GET /Endpoint
GET /HealthcareService
GET /Organization
GET /Endpoint/[id]
GET /HealthcareService/[id]
GET /Organization/[id]
PUT /Endpoint/[id]
PUT /HealthcareService/[id]
PUT /Organization/[id]
DELETE /Endpoint/[id]
DELETE /HealthcareService/[id]
DELETE /Organization/[id]

Appointment

The following endpoints have been provisionally added to the 1.2.0 specification. These endpoints will be used in future use cases and future iterations of current use cases.

POST /Appointment/[id]
PUT /Appointment/[id]
PATCH /Appointment/[id]
DELETE /Appointment/[id]

ServiceRequest

The following endpoints have been provisionally added to the 1.2.0 specification. These endpoints will be used in future use cases and future iterations of current use cases.

POST /ServiceRequest/[id]
PUT /ServiceRequest/[id]
PATCH /ServiceRequest/[id]
DELETE /ServiceRequest/[id]

1.1.0

Change Log

in BaRS 1.8.1

Change	Description	Impact
Addition of the use-context HTTP header	A new header to assist in audting and logging	Addition

in BaRS 1.8.0

Change	Description	Impact
- The DoS ID examples updated to https	The https://fhir.nhs.uk/Id/dos-service-id examples now correcly show as https.	correction
- DeviceName correction	The example deviceName element in NHSD-Requesting-Software now shows correctly as an Object as defined by the schema	correction
Appointment and ServiceRequest Features corrected.	Additional Verbs have been correctly introduced to the 1.1.0 specificiation as a correction.	Addition

Appointment

The following endpoints have been added to the 1.1.0 specification as a correction. These endpoints will be used in future use cases and future iterations of current use cases.

POST /Appointment/[id]
PUT /Appointment/[id]
PATCH /Appointment/[id]
DELETE /Appointment/[id]

ServiceRequest

The following endpoints have been added to the 1.1.0 specification as a correction. These endpoints will be used in future use cases and future iterations of current use cases.

POST /ServiceRequest/[id]
PUT /ServiceRequest/[id]
PATCH /ServiceRequest/[id]
DELETE /ServiceRequest/[id]

in BaRS 1.5.0

BaRS 1.5.0

Change	Description	Impact
Improvement to DocumentReference Schema	the DocumentReference Schemas have been flattend for easier consumption	correction

This Section will list all updates to the BaRS API Specification within the 1.1.0 minor release. Note this version is still in development

Initial release

Change	Description	Impact
Publication of the 1.1.0 Specification along side 1.0.0	1.1.0 Specification (alpha) launched	Addition
Additions of DocumentReference Endpoints	Additional header item and requirement changes for existing headers	Addition
Additions of use cases to context parameter example for GET /MessageDefinition	New parameter additions	correction
Example MessageDefinitions now contain a context code for use case.	updated examples	correction
Guidance and QoL changes	Guidance updates and corrections	correction
General	Corrections and general changes.	correction

Publication of the 1.1.0 API Specification (in development)

The API Spec page will now have a landing page to select the version of which you wish to view. At present this will present 1.0.0 and 1.1.0, with links to each specification.

DocumentReference

DocumentReference Endpoints have been added to the specification in preparation for future use cases.

The following endpoints are now available in the 1.1.0 specification. These endpoints will be used in future use cases and future iterations of current use cases.

GET /DocumentReference
POST /DocumentReference
GET /DocumentReference/[id]
PUT /DocumentReference/[id]
DELETE /DocumentReference/[id]

Parameters

The context parameter for GET /MessageDefinition has been amended to accept a use case filter The target service identifier, Allowing the ability to filter returned message definitions by the specified service id, In this example a DoS id, can now be coupled
/MessageDefinition?context=http://fhir.nhs.uk/Id/dos-service-id|2000099999&context=https://fhir.nhs.uk/CodeSystem/usecases-categories-bars|REFERRALTOPHARMACY

Guidance and QOL

Additional Guidance for the GET /Slot endpoint.

Further guidance surrounding the usage of the include query parameter for GET /Slot has been added.

General

Further Typos and/or spelling and grammar errors have been corrected

1.0.0

Change Log

in BaRS 1.9.0

Change	Description	Impact
Fixed incorrect character display on GET /Slot description	Character display for a double quote was illegible. Version 1.0.7	correction

in BaRS 1.8.1

Change	Description	Impact
Addition of the use-context HTTP header	A new header to assist in audting and logging	Addition

in BaRS 1.8.0

Change	Description	Impact
- The DoS ID examples updated to https	The https://fhir.nhs.uk/Id/dos-service-id examples now correcly show as https.	correction
- DeviceName Correction	The example deviceName element in NHSD-Requesting-Software now shows correctly as an Object as defined by the schema	correction

Initial Change Log

Change	Description	Impact
Additions to Headers and requirements change	Additional header item and requirement changes for existing headers	breaking correction
Additions and changes to query parameters	New parameters and format changes to existing parameters	breaking correction
Guidance and QoL changes	Guidance updates and corrections	correction
General	Corrections and general changes.	correction

This Section will list all updates to the BaRS API Specification within the 1.0.0 major release.

This Change log and the specification will be published in preparation for post the March 2023 post private beta release.

Headers

The Accept Header must now include a version. The version is mandatory, the specification now shows the Accept header as mandatory to reflect this.

--header 'Accept: application/fhir+json; version=1.0.0-beta'

The following Access Control headers have been made mandatory where they are currently included.

NHSD-End-User-Organisation (Required)
NHSD-Requesting-Software (Required)

The following Access Control headers have been reintroduced to the GET /metadata and GET /MessageDefinition endpoints. For consistency, the mandated items match other endpoints.

NHSD-End-User-Organisation (Required)
NHSD-Requesting-Software (Required)
NHSD-Requesting-Practitioner

Parameters

The following parameter has been added to the GET /ServiceRequest endpoint to support searching by identifiers.

ServiceRequest.identifier
- This will be a unique booking reference number/identifier of a referral, or a unique UUID/GUID for the referral. This is not the same as the ServiceRequest.id

The context parameter for GET /MessageDefinition now allows a preferred system|value format, as opposed to a value.

/MessageDefinition?context=http://fhir.nhs.uk/Id/dos-service-id|2000099999

Guidance and QOL

The descriptions and guidance for all Access Control headers have been expanded.

NHSD-End-User-Organisation (Required)
NHSD-Requesting-Software (Required)
NHSD-Requesting-Practitioner

The description and guidance for _include parameters on GET /Slot has been expanded.

expressions have been added for clarity.
minimum usage guidance added.

A simplified diagram has been added to clarify the description of the end-to-end process in the API overview.

Identified typos and spelling mistakes have been corrected.

The description and guidance for GET /metadata has been expanded.

usage and expected content has been added.
guidance on obtaining the BaRS Proxy CapabilityStatement has been Added.

General

The API Spec Version has been uplifted to 1.0.0

BaRS Proxy production URL has been added to the Environments and Testing section.

The error handling link now correctly refers to the BaRS Core implementation guidance.

Broken links within the Specifications schema examples have been rectified.

Broken links to the BaRS Standard documentation have been rectified.

Examples included within the Specifications files have been updated for clarity.

Examples referenced by the Specification have been updated for clarity.

The production environment is now listed in the Specification.

The API is now described as in production beta.