Our API policies are based on:
We have focussed on policies that are specific to APIs. We have not included policies which apply more generally to all digital services, such as clinical safety, information governance, security and the software engineering quality framework.
For some of our older APIs, it might be difficult to comply with some of the policies. In this case the approach should be to:
-
build a new API that does comply with the policies
-
deprecate and eventually retire the old API, as per our API sunsetting policy
'API first' is all about putting APIs front and centre of our digital healthcare services.
The functions and capabilities we can provide through our own user interfaces is limited by our capacity, budget, knowledge of users' needs and imagination.
By building open APIs we allow third parties to use their capacity, budget, knowledge and imagination to build healthcare software that might meet some users' needs better.
Moreover, third parties can combine our services' capabilities with their own capabilities to create novel and innovative solutions to health and social care problems.
Poor quality documentation has historically been a big pain point for API consumers. Documentation has been hard to find, and hard to understand once found.
Good API documentation aligns with our API principle to make learning easier and should include:
-
a plain English overview of what the API does
-
who can use the API, and what for - including mentioning it as appropriate in our building healthcare software guides
-
a list of related APIs
-
the status and roadmap
-
the service level
-
the technology used
-
the network access options - internet and/or HSCN
-
the security and authorisation approach
-
test environment details
-
the onboarding process
-
full technical details of the API's endpoints or interactions, including request and response examples and schemas
Documenting RESTful APIs in OAS format means our API specifications are consistent. It also allows API consumers to generate code and test harnesses more easily, which helps make design and build easier.
For more details on writing good documentation, see Documenting your API in our API producer zone (account required).
Historically, our APIs have only been available on our Health and Social Care Network (HSCN). When it was first launched - as its predecessor N3 - this was a good way to ensure healthcare systems could talk to one another securely. But HSCN presents a barrier and a pain point to people building healthcare software - HSCN connections cost money and take time to install.
Network and security technology have moved on, and it's now possible to provide secure integration for healthcare digital services on the open internet.
Internet-facing APIs help to make design and build easier.
For more details, see Network access for APIs.
Historically, our APIs have been built and deployed to a variety of hosting platforms, with a variety of different methods for authorisation, access to environments, onboarding and so on - giving API consumers an inconsistent integration experience.
If we publish all our APIs through our API platform, this gives API consumers a consistent integration experience.
It also provides a quicker and easier way for our teams to build APIs.
There may be exceptions to this rule. For example, our authentication APIs - NHS CIS2 and NHS login - are integrated with the API platform but are not proxied through it in the standard way.
Historically, getting access to integration test environments has been a big pain point for API consumers. We have made it difficult for API consumers to find out how to access test environments, and made it a manual process to get access and to get test data set up, depending on key people on our side to be available to grant access.
If we can provide self-service access to test environments, API consumers can get on with testing more quickly and easily, and it's also less burden on us.
As part of this, we need to make sure there is appropriate test data available in our environments, and where appropriate there are self-service tools for setting up test data.
This policy aligns with our API principle to make testing easier.
Historically, as an API consumer, onboarding to use our APIs in the production environment has been mentioned as pretty much the biggest pain point of all.
We have used onboarding processes that are overly manual, and optimised for our own interests, not those of the API consumers.
If we use digital onboarding for our APIs, and work to reduce the number of governance points to the bare minimum - whilst also respecting security, information governance and clinical safety - we can make it quicker and easier for API consumers to onboard.
This policy is in line with our API principle to make onboarding easier.
Last edited: 15 December 2023 11:45 am