When I try to fetch a patient’s list of allergies via REST API of the demo server, I get “Internal server error” response when the patient is new and has not registered any, yet.
Looking at the web client, the allergies are by default “UNKNOWN”, but if I set it to “No Known Allergy” I can get an empty list of allergies correctly when fetching through the API.
No known allergies (Correctly returning an empty list of allergies)
Is there a method to differentiate between an actual internal server error and unknown allergies for a newly registered patient? I want to handle both cases in the Android Client.
Hey @salahoamro I went through the core and Rest, I did find out that the issue comes from openmrs-core where UNKNOWN was not handled instead NO_KNOWN_ALLERGIES and yet Unknown allergy_status is the default value in the Patient table. That’s why when you update the value to No known allergies the empty array comes.(No error exception)
For allergies, there is an explicit difference between UNKNOWN and NO KNOWN ALLERGIES:
UNKNOWN means information on the patient’s allergies has not been established. They might have allergies or they might not. Giving penicillin to a patient without knowing if they have allergies could kill the patient.
NO KNOWN ALLERGIES means the patient’s allergies have been checked and we know the patient does not have any significant allergies. Giving penicillin to a patient with no known allergies is considered safe.
It is unsafe to assume patient’s have NO KNOWN ALLERGIES. That is why the default must be UNKNOWN. It is only safe to consider a patient as having NO KNOWN ALLERGIES once someone has made the effort to check for allergies and confirmed the patient does not have any known allergies.
It’s common for systems create a magic allergy called “NO KNOWN ALLERGIES”, but this often pushes the responsibility for properly handling the magic value to client applications and systems end up with dangerously ambiguous allergy lists that contain bothPENICILLINS and NO KNOWN ALLERGIES.
At the Java API level of OpenMRS, we wanted to avoid having a magical value for NO KNOWN ALLERGIES. Instead the Allergies object is designed to return an allergyStatus of UNKNOWN (patient’s allergies are unknown), NO_KNOWN_ALLERGIES (someone has confirmed the patient does not have any significant allergies), or SEE_LIST (one or more allergies have been recorded). There is also a method to explicitly confirm no known allergies. Unfortunately, this distinction and the proper use of is poorly documented.
What we need is not to default to NO_KNOWN_ALLERGIES (which could harm patients); rather, we need a way to communicate via REST the state of allergies being UNKNOWN that (1) does not throw a server-side error and (2) is not confused with the empty list returned by NO_KNOWN_ALLERGIES.
At first glance, it seems the RESTful equivalent to communicating “I don’t have any data on allergies” would be to return an 204 No content response when the allergy status is UNKNOWN.
Yes. If the REST Web Services module is throwing a server error (HTTP 5xx code) when allergies are unknown, I would consider that a defect. In my opinion, a client should be able to expect one of three responses when directly asking for allergies via the REST API:
204 No Content with empty body if allergies UNKNOWN (we don’t yet know if the patient has allergies or not)
An empty array if the patient has NO KNOWN ALLERGIES
If we are changing this behavior, it would be a good time to check if we return allergies within other responses and make sure the behavior is consistent (e.g., make sure we aren’t sending an empty list in a full patient response for allergies that are UNKOWN).
The only thing I’d be hesitant about is where the 500 error originates from… Often 5xx errors occur because something failed below the REST module, so fixing things there may not be appropriate if a core API also doesn’t function (I’m a little suspicious from @abertnamanya’s screen shots that UNKNOWN.equals("Unknown") is the real source of the error.
I like Burke’s API suggestion, but it does need to be clearly documented in our docs as it’s information that clients would need to be aware of.
Incidentally, FHIR’s current trial model for this is actually to return a AllergyIntolerance resource with a code indicating “No known allergies”.
I’m not a fan of a magical allergy value for no known allergies. You only have to see “No known allergies” listed amongst actual allergies once to appreciate the downside of the magical value approach.
The exceptions are varying when using demo server over qa-refapp. While the demo server throws HTTP Status 500 – Internal Server Error on the other hand the qa-refapp throws Object with given uuid doesn't exist [null]
Have tested out the three use cases and found out that the last two responses are well handled except the first one which am working out to be handled decently.
When I mentioned HTTP 204 No Content, I was referring to the HTTP status code 204, which, by definition, returns no content – i.e., no response. This would mimic a “null” value for allergies and prevent the client from having to deal with responses that might be an array of allergies or might be an object with a message saying there is no array of allergies.
If it helps, this is what I was picturing as REST responses to GET requests for allergies: