Skip to main content

Lessons from the coalface of API-first design

Our ‘API-first’ approach is making it easier for developers, suppliers and partners to connect to our platforms and services. Brian Diggle, Technical Architect at NHS Digital, gives a behind-the-scenes look at how this approach works in practice.

API (Application Programming Interface) Management is all about "making it easier to connect to our platforms and services". To achieve this, one of our guiding principles is to use the ‘API-first’ approach. I’m going to share some lessons we learned putting this into practice.

Collage image of person typing code into a computer connected with dotted lines to someone holding a smartphone.

Our challenge: designing the Summary Care Record FHIR API

Through user research, we discovered we had a problem: Our existing Summary Care Record (SCR) HL7 V3 API was overly complex for healthcare organisations and impeded (and sometimes even blocked) the use of the service.

The SCR service provides authorised staff working in different care settings access to patient information taken from their GP record. SCRs are updated when a patient’s GP record changes.

Our challenge was therefore to remove, or at least reduce, that barrier – and so release this valuable data to clinicians in order to benefit patients.

The API-first approach

In the past, when designing APIs we typically used the ‘inside-out’ approach – to look first at our internal systems (the inside) and think about how we can make them visible (the outside). The problem with this approach is that the starting position exposed lots of rather strange internal concepts which are difficult for API consumers to understand.

We had to take an ‘outside-in’ or ‘API-first’ approach to arrive at a design which would be as simple as possible for a consumer. This meant thinking about what would be an ideal SCR API from an API consumer’s perspective.

To do this we started with a blank sheet of paper and wrote out our ideal API. Once we had that, we were in a safe place to map that API onto the internal complexity of the SCR service back-end, which was not being re-designed.

Taking this approach meant that we were able to hide as much complexity (and therefore integration pain) as possible.

Our starting position was fairly close to “hide all complexity”. But there is a balance to be struck, and as we iterated our API design we found that in some cases we needed to expose more of the back-end complexity to users.

Reducing complexity - what did we hide?

Multiple back-end APIs

In order to integrate with the existing SCR service, an API consumer is required to meet 3 areas of business requirements: handling patient consent correctly, updating the SCR when new patient information is available and raising privacy alerts in some business scenarios.

Using the previous SCR API, the consumer would be required to meet these business requirements by integrating with the following 3 related APIs, which were not implemented in a uniform manner:

1. A consent handling component.

An API client was required to perform both “get” and “set” the consent status associated with a patient’s Summary Care Record. This is implemented using HL7 V3 based SOAP API calls.

2. An update handling component.

An SCR API client was required to enable the submission of patient data updates arising from new information available on the GP practice record, using a complex message format -  HL7 V3 with an ebXML compliant wrapper.

A highly available web server, exposing an API that implements a complex messaging standard, was also required. This listened for the outcome of the data update requests described above, correlated requests with responses and handled a variety of error scenarios.

3. An API client to enable the raising of alerts in some business scenarios.

In the initial design, using the API-first approach, this daunting set of requirements was reduced to a single API proxy, exposed by API Management, which contained the following 3 API endpoints. All these endpoints implemented the same API call method (REST) and used the same message format (HL7 FHIR R4):

1. A consent handling API endpoint.

Analysis of back-end implementation of consent checking revealed that it was no longer necessary to impose upon consumers a requirement to check consent because this was already being performed by the back-end service during the handling of an SCR request. Now, this API endpoint simply updates consent status by translating the FHIR R4 based standard into the HL7 V3 SOAP request required to integrate with the existing back-end consent service.

2. An update handling API endpoint.

As the back-end of the SCR service was built natively to handle updates asynchronously, the ability to change this was limited to enabling a new back-end API endpoint which the client could poll for the result. This would remove the need for SCR API consumers to stand up a web server to listen for incoming results – in itself an important step forward.

From a consumer perspective, 2 options were available to us:

  • expose the two back-end endpoints to consumers, and require consumers to poll for results
  • implement an intermediary layer in order to present a simple synchronous API to consumers

We chose the second option, even though it represented more complexity in the API itself, because the consumer first viewpoint seeks to move complexity from API consumers to API providers where possible.

3. Alerts client endpoint

Initial analysis suggested that the SCR service raised privacy alerts on behalf the API client where necessary, and therefore this component was excluded from the initial design.

A burdensome security model

The existing security model required API consumers to:

  • implement TLS Mutual Authentication – each API client would need to use a client certificate issued by NHS Digital
  • implement smartcard user authentication – the supplier solution would require deployment of software onto Windows desktop machines limiting use of the API to this setting

These requirements, on top of the existing API requirements above, made things harder for potential consumers of SCR data.

To reduce the complexity of this model, we took a consumer-first approach to security and access control, seeking to reduce barriers to the use of APIs on the platform while still maintaining a high level of data security. The platform therefore hides much of the complexity of user authentication.

For the SCR API, this means consumers are no longer required to implement TLS Mutual Authentication. Instead, the familiar OpenID Connect standard is used to authenticate users. We made this process even easier by brokering authentication to NHS Identity on behalf of users using OAuth 2.0. This further reduced the technical barriers presented to prospective consumers of the SCR API.

Additionally, software suppliers tackling integration with the SCR service are no longer required to deploy components onto practice workstations. The NHS Identity service has removed this responsibility from suppliers by providing a standard deployment asset to enable smartcard authentication. Supplier SCR integration solutions are no longer tied to Windows workstations only but may use other authentication methods available on the NHS Identity platform, such as fingerprint sensors on iPads.

Striking the right balance

We found that taking an API-first approach is about getting the balance right on the question: How much should I hide?

Our starting position was fairly close to “hide all complexity”. But there is a balance to be struck, and as we iterated our API design we found that in some cases we needed to expose more of the back-end complexity to users.

For example, our original design did not include an endpoint to enable the raising of alerts. But as we dug into the detail of the business requirements of the service, we found that there were a small number of use cases where we had to allow clients themselves to raise alerts. Information governance requirements had to override our desire for a very simple API.

In conclusion, taking the API-first approach is about where you start in terms of design. It’s about starting with an ideal API design and then re-introducing complexity where it’s required. However, because of your starting position, this should still result in an API which is as easy as possible to consume. After all, it’s all about getting that rich patient data safely and easily into the hands of those who need it.

Tell us what you think

You can suggest, comment or vote on APIs and platform features using our interactive product backlog. For example, the first iteration of the SCR FHIR API is intended only for use in primary care settings. If you would like to consume Summary Care Record data in other care settings, you can upvote and comment on Summary Care Record FHIR API - other use cases.

Please contact us if you have any question about our platform at [email protected].

Interested in working at NHS Digital? Search our latest job opportunities.


Last edited: 22 December 2021 1:54 pm