Responding to queries

You can use queries for synchronous requests, which include the REQUEST or RESPOND types of API actions. You’d do this when querying for data from your connection or responding with data to your connection’s query. Either way, the system that requests data waits for a response from the destination the query is sent to.

Like everything else in life, some requests work out and others don’t. We’re happy to let you know the fate of your request either way, and we have some details about each scenario below.

For queries, you receive one response with two parts: The HTTP status code from Redox and the results of your query from the destination system.

There are three scenarios for synchronous responses.

Best case scenario: Redox successfully processes and delivers your query to the intended destination, and the destination successfully accepts the request and returns results.

If so, you receive a 200 OK status from Redox. The response body contains the requested data from the destination system. The fields and values present are specific to the data model or FHIR® resource you sent.

Occasionally, Redox successfully processes and delivers your request, but an error occurs within the destination system, so it fails to accept the query.

If this happens, you still receive a 200 OK status from Redox, but the body of the response contains an array populated with error data:

1
{
2
   "Meta": {
3
     …
4
     "Errors": [
5
       {
6
         "Text": "Destination returned an error response.",
7
         "Module": "Destination Response",
8
         "DestinationStatusCode": 401,
9
         "Details": "Not authorized to access this patient."
10
       }
11
     ]
12
   }
13
 }

1
{
2
		"resourceType": "OperationOutcome",
3
		"issue": [
4
			{
5
				"severity": "error",
6
				"code": "invalid",
7
				"details": {
8
					"text": "Unknown search parameter name \"foobar\" for model \"Patient\"",
9
					"coding": [
10
						{
11
							"code": "MSG_PARAM_UNKNOWN",
12
							"system": "http://terminology.hl7.org/CodeSystem/operation-outcome",
13
							"display": "Parameter \"foobar\" not understood"
14
						}
15
					]
16
				},
17
				"diagnostics": "Failed to execute FHIR search"
18
			}
19
		]
20
	}

Worst case scenario: Sometimes, your query fails within Redox, which means we fail to process and deliver it to the intended destination.

If the error occurs within Redox, you may receive a 4XX or 5XX HTTP status. Review HTTP errors.

When you receive a synchronous query from your connection, we wait for you to send back a response with the results of their request. Then, we return it to your connection in the format indicated in their request.

When you successfully receive a query from your connection, you should send back a 200 OK status with a response type that matches the query request.

Here’s an example: The destination’s EHR system triggers an alert when a provider wants to order a new medication for a patient. But the provider wants to review the patient’s data before deciding on a specific medication. So, the EHR system sends a ClinicalDecisionsSupport request for more data. Your system successfully processes the request and aggregates results with the relevant data. You respond to Redox with a 200 OK status and the ClinicalDecisionsSupport.Response data model.

That’s the kind of response everyone hopes for.

However, failures can’t always be avoided. There are two scenarios for failed deliveries to your system.

If we don’t hear back from you after a couple of minutes, the original request times out. We let the source system (i.e., your connection who sent the query) know that their request wasn’t received. The source system can then retry sending if they want.

If an error occurs in your system that prevents you from successfully receiving the synchronous request from us, your system should send back the relevant 4XX or 5XX HTTP status code and a response with the relevant data populated:

We send the failed status code and the response with the errors back to your connection so they can review the log details.