GP Connect Appointments FHIR API Implementation Guide

Along with some others, I’ve been asked to review the NHS FHIR API proposals [] and provide feedback. At the moment there isn’t an open review mechanism so I’ve no idea if issues have already been raised!

To help others, I’m going to publish issues here so that we have shared record for anyone to read and comment.

Hi Dunmail - there was a further workshop with the principal suppliers regarding the Appointments API earlier this week. We are currently amending that spec and a new version will appear shortly.

The changes to the profiles are minimal the main changes are in describing the API nature of the API (if that makes sense!).

Great - the spec was light on implementation detail!

Could we have examples on how the API is accessed?

Do we intend to use REST API using FHIR like calls. i.e. GET Observations?subject=NHSNumber etc.

The implementation guide is still a work in progress, but appears to be sensible and coherent!

Typo, throughout - ‘Principle’ systems -> ‘Principal’ systems.
NB: Just aligning with GPSoC wording, rather than casting aspersions on the Principal system vendors :slight_smile:

In scope

_sort query parameter should be available on all _search operations e.g. sort available appointments by date asc, so the first available appointment is first in the list.

If chained parameters are limited to patient identifier, would it not be cleaner to use a FHIR Compartment e.g. [base]/Patient/12345/Medication? We’ve been looking at FHIR authorisation recently and this provides an implementation (it is a stated intent of compartments) that works with a more granular authentication and authorisation model. This is already specified for Appointment searches.

Out of scope

Typo - Whole system ‘SEACH’ -> ‘SEARCH’

Comparators for search - in our experience these are required, for example slots from 11am to 3pm tomorrow. At minimum, suggest that at least the gt, lt search parameters are available for date searches. The search specification later provides this - need to update the scope section accordingly.

Is paging of search results in scope? This is a useful capability, but needs some thought about the implementation. If so, _count parameter for search becomes useful.

Endpoint resolution

There is a mandatory reliance on SDS and Spine. I can understand the rationale behind this decision, but it’s not as this creates a substantial barrier to adoption for new entrants.

I suggest that the requirement to use this approach be relaxed. For many settings, the information is already available from local directories which would be fit for purpose.

Restful API

Resource type

'Clients and servers SHALL support the following FHIR resource types’
Clients need not support all the resource types (e.g. a patient SMS client does need to support AllergyIntolerance).

By Conformance resource, does this mean that FHIR servers support the Conformance resource (i.e. we can read/write/update different Conformance resources) OR that the FHIR servers must return a Conformance resource describing the server capability from the GET / and GET /metadata interactions?

Provenance and audit headers

We’ve put forward a proposal to include FHIR-specific claims within JWT that may be worth considering:

Managing return content

Is Prefer: return=minimal needed for a minimum viable product?

Managing resource contention

Typo: resource vesionId -> versionId

Resource references

I don’t like making things mandatory, but meaningful display text is a massive help. It may be worth providing guidance around the length of the display field so that UX designers can manage it appropriately, possibly on a per instance basis e.g. references to organisations might be defined as their name, followed by ODS code such as ‘Somewhere Medical Practice [Q65432]’

create, update interactions

In our experience we’re often using operations to manage creation and updates of resources (for further discussion of the rationale behind this see CQRS pattern e.g. Requiring a client to create an entire new resource requires extra work on both client and server. The client has to create a complete, valid resource. The server has to validate a complete resource, including integrity checks.

Find a patient

If NHS Number is the national identifier then surely we don’t need dofb as well!

Find a practitioner

How easy is it to determine SDS user IDs?
Is it possible to search for all Practitioners on the FHIR server (i.e. all the staff at a practice?)

Find a location - response

'As outlined in the FHIR standard, clients SHALL handle servers returning a bundle of requested resources, '
Not sure what this is getting at - if a client requests a search interaction, they get a Bundle back …

Retrieve HTML Care Record

This should be an instance level operation. This would simplify the implementation e.g. there are errors to handle the case where the NHS number isn’t found.

Still WIP, but some thoughts:

Should the patientNHSNumber parameter be an Identifier, constrained to use the NHS Number system? This would be more general and allow for alternatives in the future

Different time periods per resource class would reflect real world requirements e.g. All problems, but only last 3 months medications and investigations. If this isn’t in the API then I expect we’ll have to proxy the API and filter ourselves as this is important for best practice in data sharing.

Is there any guidance about the formatting of the HTML Care Record? This has significant implications for clinical safety, particularly in other contexts of use. For example, an html view requiring a 800x600 port may not be safe on a phone. Is a responsive design required? Would this not take longer to create and validate than just sending the structured record and requiring the client to take responsibility for the presentation? Will the view be consistent between providers?

How is the HTML carried in the response?

Retrieve Structured Care Record

How will this be differentiated at an implementation level from the HTML Care Record operation?
How will the HTML Care Record compare to the resource.text.div?

Task interactions

Assume that will be reference(Organization|Practitioner). Is it wise to allow Practitioner as recipient organisations may need to route to the appropriate person e.g. when staff on leave? This will depend on how it’s handled in the recipient system but could create clinical safety risk.

Does the task-description extension provide anything that couldn’t be handled by populating the order.text.div (i.e. the resource narrative)? The description is not computable, anyway.

After recent discussions with system users they felt that tools to curate inbound messages are weak in existing systems (e.g. it’s not possible to prioritise lab results with out of range values). They proposed that an indicative date & priority on the inbound order would be very useful. I think priority would be covered by the reason codes.

The example order doesn’t have order.detail so would not be a valid Order. I think you’ve identified a case for a generic Order that doesn’t relate to another resource.

Should these points be raised with the FHIR team?

Re: Paging

Agree with Dr Stables comment about paging being more difficult to implement, combinations of date ranges and _count may be more practical. Dunmail’s comment about supporting _count is useful (when using a search on NHS number we’ve found _count and sort order useful).

Wonder if OAuth/Security should be a separated out into it’s own stream. It’s a general (RESTful interface) requirement not a only FHIR requirement, i.e. I would expect openEHR interfaces to support the same security mechanism.

Agree that OAuth/Security is a separate topic, but we also need to ensure that it ‘plays nicely’ with the systems being accessed - a FHIR-oriented token will be hard for OpenEHR systems to utilise and vice versa.

Not sure of the practicality of a FHIR orientated token. Partly following on from the consent topic, I’d prefer to see general agreement OAuth2 is the correct approach and then move forward.

My main requirement at the moment is enterprise security and locking down RESTful API’s. I’d also like to be able to extend that, probably incorporating consent (plus FHIR resource security) at a later point. Thats probably reducing the requirement to the points you mentioned in the consent thread about authentication and RBAC.

I’ve gone for OAuth2 at present via java+Spring Security as it allows us to swap authentication methods and introduce RBAC (when we’re asked for it).

The token works in conjunction with OAuth2 by carrying the claims from the authentication provider and making it easy for a FHIR server to comply. At an implementation level, it’s easy to check that the user is authorised to ‘read Medication for Patient 123’.

re: Tokens: Sorry my wording - I meant we don’t need to implement it at the moment but want to have a framework that allows us to move to that with minimal disruption.