Understanding Endpoints

Using the request explorer is a good way to get started, but to make a real application you’ll need to communicate directly with a FHIR endpoint.

An endpoint is just a URL where you can submit requests for FHIR operations. A given site may have any number of endpoints, each with a different URL and potentially different restrictions, available data, or supported FHIR versions. For example, a site may have one endpoint for the DSTU2 version API and another for the STU3 version API. It may have one endpoint for read-only access and another for read-write access.

You will need to know the endpoint URL to perform any FHIR operations.

FHIR Directory

Each HIEBus system maintains a FHIR directory page, which you can find by adding /fhir to the CareEvolution system URL.

On the CareEvolution public test server, the FHIR directory can be found at https://fhir.careevolution.com/Master.Adapter1.WebClient/fhir/. You can also access it by selecting “Documentation” from your account home screen.

Browse the FHIR directory to find information about the FHIR interface specific to that system, including:

• What endpoints are available.
• What data resources are available through each endpoint.
• What coding systems are in use.
• etc.

API Endpoints

The FHIR directory is for user reference. Each endpoint also has a different URL for API calls, often called the base API endpoint. You can find this URL on the FHIR directory page.

For the CareEvolution public test server:

Throughout this guide, you’ll see [base] used to refer to the base API endpoint. For example, [base]/Patient/1 would translate to https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir/Patient/1 using the public test server’s DSTU2 endpoint.

Capability Statement

In addition to the FHIR directory, each endpoint provides a capability statement (known as a “conformance statement” in older versions of the FHIR specification) that describes the details of the FHIR interface implementation. The capability statement includes:

• FHIR interface version.
• Authentication endpoints.
• Supported resources, search fields, and operations.
• etc.

It is similar to the information in the FHIR directory and interface specification, but provided in XML and JSON forms for easy consumption by software applications.

The URL for the capability statement is:

[base]/metadata

For example: https://fhir.careevolution.com/Master.Adapter1.WebClient/api/fhir/metadata

Returns:

{
    "resourceType": "CapabilityStatement",
    "contained": [
        {
            "resourceType": "OperationDefinition",
            "id": "operation-add",
            "url": "http://careevolution.com/fhir/OperationParameter/group-add",
            "name": "Adds members to a group",
            "status": "active",
            "kind": "operation",
            "experimental": false,
            "idempotent": false,
            "code": "add",
            "resource": [
                "Group"
            ],
   ...