PDS API Patient search returns an OperationOutcome resource under some circumstances

Personal Demographics Service (PDS) Personal Demographics Service FHIR API
,
1

We’re running a test-case for multiple matches against the INT environment using parameters:

{
  birthdate: '1982-06-08',
  gender: 'male',
  family: 'XDJ-JUN-ALLOC-ALGO-MULTI'
}

The response has status 200 with an OperationOutcome resource containing an issue with code multiple-matches.

FHIR R4 search provides 2 alternative responses.
“If the search succeeds, the server SHALL return a 200 OK HTTP status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero or more resources in a defined order.”

“If the search fails (cannot be executed, not that there are no matches), the return value return value SHALL be a status code 4xx or 5xx with an OperationOutcome.”

We expected the OperationOutcome to be included as an entry of type outcome in the Bundle.

2

Can I ask what level of access you’re using for these searches?

To potentially pre-empt the answer, if using Application-restricted access:

In this access mode, you only get a single matching patient record, and only if it’s a unique match.

This is documented on Personal Demographics Service - FHIR API - NHS Digital

3

We are indeed using Application-restricted access and are testing the case where there are multiple matches.

As this is a FHIR search, the API should respond with one of the combinations of HTTP status and FHIR resourcetype as outlined above (i.e. 200 Bundle | 4xx/5xx OperationOutcome). The PDS API documentation says the response will be “HTTP status: 200. A completed search. This might contain zero, one or many matching patients, or it might contain a ‘TOO_MANY_MATCHES’ error.” We therefore expected HTTP status 200 and a FHIR Bundle containing an OperationOutcome as an entry.

PDS API is responding with HTTP status 200 and a FHIR OperationOutcome. This is consistent with the PDS API documentation but isn’t consistent with FHIR (requiring workarounds to be applied in the client).

Is this as intended?

4

I get what you mean.

Wouldn’t it be better with a 422 and OperationOutcome?
The search has not been performed and 200 at a basic level indicates all is ok (but it isn’t)

5

I think a case can be made for both 200 and 4xx responses (e.g. 422) - either could be made to work.

As the search is a valid one that the server has processed (in order to determine that there are multiple matches) it seems a little harsh to class this as a Client Error. The only way a client application could avoid this error would be if it already had a priori information allowing it to uniquely identify a single individual within the UK!

6

From memory (when we designed this bit) we went back and forth on what response code to return. I was the product owner at the time and was a but uneasy about returning a 200 with an OperationOutcome but as you say it seemed the most appropriate response since the search had indeed been processed - 4xx typically implies some sort of mistake on the caller’s part, whereas in this scenario there’s nothing wrong with the request.

1 Like
7

NHS API Management team let me know that there is currently no intention to change the API behaviour to conform to the FHIR standard.