Reading resources
Requirements
FHIR resources are the core of the Flexpa Patient Access APIs. Patients authorize your app to access their resources via Flexpa Link. At the end of that flow you'll have:
After the authorization, you can make HTTP requests to Flexpa API using the access token to pull specific resources.
Reading resources
A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.
Reads on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource.
In the event that you do not have a specific ID of a resource, you'll likely want to use the search operation instead.
Please note: A FHIR request without any parameters may appear to be a read operation, but is treated as a search operation. Some servers may not support this and will return an error. It is best practice to either perform a read operation or to always include at least one search parameter. Most commonly this parameter will be the patient ID.
You can read more about the read operation in the FHIR specification.
Example read request
A very common use of the read operation is to retrieve a patient's core demographics (e.g., name, address, etc.). This is done by reading the Patient resource using the patient ID returned in the access token.
You can retrieve the patient ID by either:
Here's an example of that read request:
ACCESS_TOKEN=... # replace with the access token you obtained at the end of the Flexpa Link flow
curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID" \
-H "Authorization: $ACCESS_TOKEN"
Response type
The return type of a successful read is the resource itself, in contrast to the Bundle returned by searching.
In the event of a failed read, an HTTP 4xx error is returned. Unknown resources and deleted resources are treated differently on a read: a GET for a deleted resource returns a 410 Gone status code (see the delete interaction for additional details), whereas a GET for an unknown resource returns 404 Not Found
Example read response
In response to the Patient example above, you'll receive a Bundle like this:
Referenced resources
Many resources returned by the API will contain references to other resources. For instance, a Patient may contain a reference to an Organization or a Practitioner. When you receive a resource with a reference, you can use the reference to make a request to the referenced resource.
For resources that have many references, the number of subsequent API requests needed to pull all referenced content may be quite high. As a result, when supported, it's common to use the _include parameter to include the referenced resources in the response. This is especially useful when you want to display a list of resources and their related resources in a single request.
Read more about the FHIR definition of the _include parameter here.
Example read request with _include
ACCESS_TOKEN=... # replace with the access token you obtained at the end of the Flexpa Link flow
curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID?_include=*" \
-H "Authorization: $ACCESS_TOKEN"
Contained resources
When reading resources, you may encounter resources where the referenced resource is actually contained in the API response and not a separate external reference.
For instance, rather than point to an external Organization resource, a Coverage resource may contain the Organization that is the insurer for that coverage. When you receive a resource with a contained resource, you can access the contained resource by using the resourceType and id fields.
Example contained resource
{
"resourceType" : "Coverage",
"contained": [
{
"resourceType" : "Organization",
"id" : "o1",
"name" : "Cigna Insurance"
}],
"insurer" : {
"reference" : "#o1"
}
}
Next steps