NHS Open API Architecture Policy

Dunmail -

Core API Access is consistent with the NHS Open API Architecture Policy.


C.1 Scope

“All significant business functionality provided by the host system should be available via an Open API.”

Core API access is used by Black Pear apps and therefore includes all significant business functionality.


C.2 User

“For each exposed API, there is a need to understand if the consumer of the API requires to be identified.”

Core API access requires the consumer of the API to be identified and is subject to RBAC.


C.3 Documentation

“Each API should be documented to the extent that a competent developer has sufficient information to make use of the API without further information. All actions (methods) that are available through the API should be covered, as well as the legitimate data (classes) and return codes. Sample code should be made available. The documentation should be freely available.”

Endpoints provided via Core API access comply with published industry standards. HL7 FHIR implementation guides and capability statements are published.


C.4 Testing

“A testing environment (or environments if appropriate) should be provided which allows developers of the solutions making use of the API to test their solutions without affecting production environments, or an authorised process provided to support the understanding, development and testing of the API.”

Test and staging environments are available for Core API.

Administration and usage charges apply.


C.5 Availability

“For each capability of the API (method) the API agreement should specify when the API should be available. Commercial terms need to be clear on the definition of responsibilities in any service management agreement.”

Core APIs are available 365x24 with 99.5% availability.


C.6 Performance

“For each capability of the API (method) the API agreement should specify what are the Service Level Agreements (SLAs) for the response times of the API. This will be dependent on the API software and also the hosting and other dependant infrastructure, data volumes and other interfaces with systems.”

The API agreement does not define a SLA for response times. Response times depend on third party systems that are not within Black Pear's control. Black Pear will provide information around known performance characteristics.


C.7 Usage

“The number and type or requests the user should be able to make in a given time period, and the quality (compliance with sending well-formed requests etc.) standards required for those requests.”

The API agreement will define the rate and volume of requests and set expectation that users send well-formed requests.


C.8 Quality and accuracy

“The quality criteria for the API must be specified.

The API should return the same data that would be retrieved were the same function being performed within the host system.”

Core API access is used by Black Pear apps and therefore returns the same data.


C.9 Access: Registration / Accreditation / Termination

“The approach specifies how a user can access the API, including any requirements for accreditation to ensure that their (proposed) access meets required standards, both technical and governance, and when such access ends.”

Core API access is subject to accreditation and is limited to the period specified in the API agreement.


C.10 Commercial / financial considerations

Anonymous usage should be free, but Identified usage may (but need not) carry charges based on the specific requirements of the host system such as a fixed rate per month, a one-off fee or a fee per usage, or per number of records, quantity of data returned, amount of resource required to process the call.”

Core API access offers Identified usage.

Administration and usage charges apply.


C.11 Information Rights

“Any terms and conditions regarding the use of the data acquired via the API including security, retention and destruction policies. The rights and obligations of the API user regarding all data returned by the API should be made explicit.”

Data provided via Core API access are subject to a Data Sharing Agreement with the Data Controller on whose behalf Black Pear process the information.


C.12 Changes to the API (versioning)

“API should retain backwards compatibility with earlier releases. Where delivery of the API is specified by the procuring organisation; changes to the API which break backwards compatibility require the approval of the procuring organisation (or body acting on behalf of all such procurers) as per the contract.”

Core API endpoints are versioned using semantic versioning.

Changes to test environments are managed as per Black Pear Base SLA.

Changes to production environments are managed as per Black Pear Standard SLA.



Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk