Stream: implementers
Topic: OperationOutcome that allows code to recover and carry on
Silvia Lillie (Jul 17 2018 at 07:45):
[As a developer creating APIs that exchange data via FHIR, I want to return good OperationOutcomes so that third parties using my APIs can write robust applications]
In a scenario where
- custom operations are used, and
- the input is a Parameters resource containing parameters
-- both of simple and complex datatypes and
-- where there might be repetitions,
how can I return meaningful data in an OperationOutcome that allows the consumer code to identify the error and recover in a production environment?
Specifically:
-
How is the parameter at fault identified? Is the xpath really useful to anyone? Is it realistic to expect that the caller would save the request text every time, so that in case of error they are able to apply the xpath and get to the parameter?
-
Has anyone got round this by, for example, creating extension called "fieldName" and "fieldValue" to make it easier to pinpoint the specific data item that has caused the error?
The issue is not so much if the error is triggered during development (as the devs will have an opportunity to analyse the request message they sent). But when an error happens in live scenarios, the application consuming the FHIR needs to get over the error and carry on.
Example:
- custom operation to search for free appointment slots at a number of HealthcareServices
- Input is: HealthcareService Identifiers (1..*), date range
- error: one of the HealthcareServices (which was a valid entry yesterday) has just been wound down and is shut from today onwards.
- expected flow: OperationOuctome says Service ID =1234 is no longer valid, third party code removes the specific entry and runs the search again, having appropriately warned the user.OperationOutcome that allows code to recover and carry on
Thank you
Lloyd McKenzie (Jul 17 2018 at 13:29):
OperationOutcome is intended to be useful for more than just operations. "Field name" would be specific to Parameters, so we'd rather have a generic solution. XPath and FHIRPath provide that. They're simple position-based paths, so pretty easy to parse and process.
Silvia Lillie (Jul 19 2018 at 10:38):
Thank you @Lloyd McKenzie ,
so you mean that API consumers are likely to have a way of surfacing all the various types of errors from the FHIR-handling libraries up to the business logic classes?
I wouldn't assume that my API consumers have a FHIR server at their end, although we strive to use FHIR for the data in transit.
And, as the supplier of the API, how do you provide support if all you have to go by is the error code and the FHIR path (and not the actual value that was the problem)? Would you log absolutely everything going in and out ahead of the strings being processed?
Lloyd McKenzie (Jul 19 2018 at 14:26):
An API consumer may or may not have the ability to surface the error location or other information. It may be that all it'll do is keep track of success vs. failure and perhaps display a big red X in the event of the latter. However, the API tries to allow a useful/reasonable amount of detail to be communicated back. The details about what the problem was would be conveyed in OperationOutcome.details - as either a local code or text or both. And you could include a full stack trace or equivalent in OperationOutcome.diagnostics. That doesn't mean you might not also log the failure, but you should be able to convey enough information in the OperationOutcome that you wouldn't have to rely on that.
Last updated: Apr 12 2022 at 19:14 UTC
