FHIR Explorer

The FHIR Explorer lets you quickly build HL7® FHIR® queries based on your server’s capability statement, execute them, and display the results both in JSON format and in a summary table. This provides the opportunity to optimize your queries, and allows you to explore the data in your server.

The FHIR Explorer is organized into the following tabs:

Configure

Here you specify what server you wish to query, choose an authentication method, and provide the required credentials. After you provide these, the FHIR Explorer loads your capability statement.

Build

This is where you build queries, specifying scope, resource types and parameters, and the level of strictness you wish to apply. This interface provides two linked methods to develop your query: a text box, and a series of fillable forms. When you enter information in one method, that information is reflected in both. That is, if you enter a Resource type in the text box, that Resource type also appears in the relevant form field. Both methods feature autocomplete functionality based on your capability statement.

Results

Here you can view the data provided in response to your query.

To use the FHIR Explorer, open the Management Portal and navigate to Health > FHIR Server Management > FHIR Explorer.

Configuring the FHIR Explorer

On the Configuration tab, you provide the address and credentials needed to contact the FHIR server you wish to explore.

To configure the FHIR Explorer:

In the Target FHIR Server field, either choose a base URL from the drop-down list, or enter the base URL for the desired FHIR server. This is the instance URL, followed by the endpoint path. For example:
```
https://localhost/my_instance/csp/healthshare/my_foundation/fhir/r4
```
Note:

When you enter a URL in this field, it is added automatically to the drop-down list to facilitate future use. To remove a URL from the drop-down list, click its trash can icon.

At this point the FHIR Explorer attempts to find the capability statement associated with the specified FHIR server. The autocomplete suggestions in the query building fields on the Build tab are based on information from the capability statement. If the FHIR Explorer cannot find your capability statement, a warning banner is displayed, and autocomplete will be limited to Resource types based on the specified FHIR version.
In the Server Authentication section, choose an authentication method from the Authentication Type drop-down list, then enter the appropriate credentials in the remaining fields:
- For Unauthenticated, no credentials are required. However, it is not recommended to make unauthenticated requests for sensitive data.
- For Basic Authentication, enter the username and password.
- For Bearer Token, enter a bearer token.
- For X-API-Key, enter the API key.
Click Next to authenticate using the specified credentials and to switch to the Build tab. If you prefer not to authenticate, you can simply click Build to switch tabs.

Building Queries in the FHIR Explorer

On the Build tab, you can create and test queries that make requests from your FHIR server. You can enter your query by hand in the Search Query field, or you can use the form in the Query Builder area of the screen. Both methods feature autocomplete suggestions based on the specified FHIR version and your capability statement.

The two methods are linked, so that entering information in the Search Query field populates the equivalent sections of the form in the Query Builder area, and vice versa. This makes it easy to go back and forth between the two methods.

To build and execute a query in the FHIR Explorer:

Decide the level of strictness you wish to apply to request parameters, then choose the corresponding radio button in the Request Parameters section.
- Strict Handling – Invalid parameters return an error.
- Lenient Handling – Invalid parameters are skipped, and reported in the Operation Outcomes on the Results tab.
Determine the search context for your request, then click the corresponding button in the Search Context box.
- Resource Type searches a single specific Resource type. For example, if you know you are looking for a Patient, choose this option.
- Search-System searches on the union of multiple Resource types. For example, if you are looking for a person named ‘Alex’ but are not sure whether they are a Patient or a Practitioner, choose this option.
- Compartment searches for all items related to a specific instance of a Resource. For example, to gather all information about Patient/123abc, choose this option.
Begin typing your query into the Search Query field. The FHIR Explorer responds as follows:
- Autocomplete options appear in the Search Query field. For example, if you type “Pa”, you will see autocomplete suggestions for Parameters, Patient, PaymentNotice, and PaymentReconciliation.
- Additional forms appear in the Query Builder area, which allow you to add search parameters, search result parameters, includes, and revincludes.
- The information you entered in the Search Query field populates into the corresponding fields in the Query Builder forms.
Continue constructing your query, either by typing in the Search Query field or by choosing the + Add ... buttons and entering text in the fields associated with the Query Builder forms. These forms offer autocomplete options based on the specified FHIR version and your capability statement. You can go back and forth freely between the forms and the Search Query fields.
When you are satisfied with your query, click Execute. Focus shifts to the Results tab, where you can view the results returned in response to your query.

Viewing Results in the FHIR Explorer

On the Results tab, you can view the results sent in response to your query.

The Results tab provides the following information:

Results for

The request that generated this response.

Timing

The length of time, in milliseconds, that the system took to process the request.

Timestamp

The date and time at which the request was processed.

Status

The status code returned with the query response. For example, 200 OK.

Operation Outcomes

A list of any errors, warnings, and information messages associated with the request. You can use these, for example, to refine your query or troubleshoot your server.

For more information, see Operation OutcomesOpens in a new tab in the FHIR specification.

FHIR Resources

A table displaying the ID, Resource type, version ID, and the date and time of last update for each Resource included in the query results.

Click a row in this table to display the full JSON object for the selected Resource.

You can expand and collapse all blocks displayed in the JSON by clicking Expand All or Collapse All. To dismiss the JSON, click its X icon.