What do I need to know in order to test the API?
The above question leads to a series of follow-up questions, such as:
- What API request fields are available, additionally which subset of those are required vs optional.
- What API request fields map to what filtering fields, so that we can query against our data sources for validation (generally in API implementation specification documentation).
- If there isn’t a direct tie to specific input fields, then we need an understanding of how to interpret the request into our SQL WHERE clause for validation.
- What API response fields are available, additionally which subset of those are required vs optional if any are optional.
- Any conditionalities that apply (ie. if the API returns different data if run with specific criteria)
Performing testing against FHIR APIs requires some basic FHIR knowledge
Understanding FHIR Implementation Guide APIs:
- In the Patient Access API effectively all queries are bounded by the Patient Id.
- Queries are limited to SEARCH and READ
- A query is a search at the resource level with parameters that would include “_patient=Patient/[ID]”
- Search Parameters are typically defined by the relevant FHIR Implementation Guides.
- For CARIN-BB the supported parameters are defined here: http://hl7.org/fhir/us/carin-bb/searchparameters.html
- For US Core Clinical resources the search parameters vary based on the type of resource. The types of search values are shown here: https://www.hl7.org/fhir/us/core/searchparameters.html
- For Formulary: search parameters are primarily limited to searching on DrugName, Drug Plan and Drug Tier. One of the changes to Formulary is that a member will only see the drug plan that they are signed up for. The search parameters are shown here: http://hl7.org/fhir/us/davinci-drug-formulary/artifacts.html#behavior-search-parameters
- For Provide rDirectory there are a large number of search capabilities. These are documented here: http://hl7.org/fhir/us/davinci-pdex-plan-net/STU1/artifacts.html#behavior-search-parameters
- Generally a FHIR Search Parameter is entered as follows:
- A search is made to the relevant FHIR endpoint. e.g., [base]/Practitioner?[FHIR field name]=[search_value]
- In many cases the Profile page for a resource in the relevant FHIR Implementation Guide will provide example searches.
- The FHIR Release 4 Specification also has a page on Searches. It identifies the common search parameters that can be used for any resource. The page is here: http://hl7.org/fhir/R4/search.html
General Information about Searching FHIR APIs
A FHIR search will return a bundle. In most FHIR Servers a bundle will be paged and the search will return up to 10 records.
If you include “&_total=accurate” in the search parameters you will also get a count of the total records that could be returned from the search.
If more than one page is needed to return all the records in the search you can look in the link object in the FHIR bundle and get the URL to page through to the next page in the bundle.
One thing to be aware of: A FHIR ID is not the same as an Identifier. A FHIR ID is typically part of the URL. It enables a specific FHIR record to be referenced. E.g. [base]/Patient/123456. An Identifier is a business identifier, such as a Provider’s NPI. Business Identifiers are typically searchable and they are found in the content of the JSON record returned. A FHIR record can have multiple business identifiers. For example, a Practitioner or Organization record might have an NPI, a Tax ID and an identifier issued by the payer. Identifiers can also be a historical record in that a period can be defined (Start and End Date) during which an identifier is valid.
Obviously the amount of detail available in a FHIR Record is dependent upon the data that was loaded into the record.
When records are updated in a FHIR Server the “meta” section of the record is updated. This will increment the version number of the record and the “lastUpdated” field will be updated with the time and date of the last update. The LastUpdated date is often used in searches to limit the information returned to just those records that have been updated since a specific point in time. For example:
[base]/Observation?_lastUpdated=gt2020-10-01
Therefore, a variation of the above search could be used to query which observation records have been updated in the previous 24 hours. This is beneficial for both app developers and data holders by limiting the amount of data being queried. Typically, an App developer will make a first call to a resource and ask for everything and then subsequent calls would request everything since the last check.
With the Patient Access APIs it is important to remember that the searches will typically be bounded by the Patient ID for the member that authenticated and authorized the sharing of their information. Effectively adding “&patient=Patient/12345” to each query.
A FHIR search request will typically return all of the data in an individual record. This behavior can be overridden by including “&_summary=[option]” in the search parameters. The options are laid out here: http://hl7.org/fhir/R4/search.html#summary
Which pieces of data are returned in the summary option depends upon the option chosen and on how the FHIR profile specification for a resource has identified individual fields for inclusion in the summary view.
[]: