eMedicalPractice v2.0

Excelling in Electronic Healthcare Solutions

eMedicalPractice FHIR API Documentation

FHIR API Table of Contents

Overview

Easy-to-use JSON-based REST API for eMedPractice FHIR. See standard eMedPractice API docs here. The eMedPractice FHIR API conforms to the R4 specification and the US Core 3.1 Implementation Guide (IG).

Prerequisite

Enable the Standard FHIR service (/fhir/ endpoints) in eMedPractice menu: SiteAdmin->FhirSetup->"Enable eMedPractice Standard FHIR REST API"

Authorization

eMedPractice uses OIDC compliant authorization for API. SSL is required and setting baseurl at SiteAdmin->FhirSetup->'Site Address (required for OAuth2 and FHIR)' is required.

See Authorization for more details.

FHIR API Documentation

The FHIR API is documented via Swagger. Can see this documentation (and can test it) by going to the swagger directory in your eMedPractice installation. The FHIR API is documented there in the fhir section.

Standard FHIR endpoints Use https://fhirbackup.emedpractice.com:8443/ as base URI.

Example: https://fhirbackup.emedpractice.com:8443/r4/Patient returns a Patient's bundle resource, etc

The Bearer token is required for each eMedPractice FHIR request (except for the Capability Statement), and is conveyed using an Authorization header. Note that the Bearer token is the access_token that is obtained in the Authorization section.

When registering an API client to use with Swagger the following for the redirect url and launch url for the client.

Request:

curl -X GET 'https://service.emedpractice.com:8443/r4/Patient' \-H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNnZ3eGJZYmFrOXlxUjF4U290Y1g4QVVDd3JOcG5yYXZEaFlqaHFjWXJXRGNDQUtFZmJONkh2cElTVkJiaWFobHBqOTBYZmlNRXpiY2FtU01pSHk1UzFlMmgxNmVqZEhcL1ZENlNtaVpTRFRLMmtsWDIyOFRKZzNhQmxMdUloZmNJM3FpMGFKZ003OXdtOGhYT3dpVkx5b3BFRXQ1TlNYNTE3UW5TZ0dsUVdQbG56WjVxOVYwc21tdDlSQ3RvcDV3TEkiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6ImZoaXIifQ=='

Capability Statement

GET fhir/metadata

This will return the Capability Statement. Note this can be tested by going to the url GET 'https://fhirbackup.emedpractice.com:8443/metadata' or sh curl -X GET 'https://fhirbackup.emedpractice.com:8443/metadata'

Provenance Resources

Provenance resources are requested by including _revinclude=Provenance:target in the search of a resource. Is currently supported for the following resources:

BULK FHIR Exports

An export operation that implements the BULK FHIR Export ONC requirements can be requested by issuing a GET request to the following endpoints:

You will get an empty body response with a Content-Location header with the URL you can query for status updates on the export.

To query the status update operation you need the system/*.$bulkdata-status scope. An example query:

A status Query will return a result like the following:

                        {
                            "transactionTime": {
                                "date": "2021-02-05 20:48:38.000000",
                                "timezone_type": 3,
                                "timezone": "UTC"
                            },
                            "request": "\/apis\/default\/fhir\/Group\/1\/%24export",
                            "requiresAccessToken": true,
                            "output": [
                                {
                                "url": "https:\/\/fhirbackup.emedpractice.com:8443\/r4\/Document\/97552\/Binary",
                                "type": "Patient"
                                },
                                {
                                "url": "https:\/\/fhirbackup.emedpractice.com:8443\/r4\/Document\/105232\/Binary",
                                "type": "Encounter"
                                }
                            ],
                            "error": []
                            }

You can download the exported documents which are formatted in Newline Delimited JSON (NDJSON) by making a call to: sh curl -X GET 'https://fhirbackup.emedpractice.com:8443/r4/Document/105232/Binary'

In order to download the documents you will need the system/Document.read scope.

Bulk FHIR Scope Reference

3rd Party SMART Apps

eMedPractice supports the ability for 3rd party apps who implement the SMART on FHIR App Launch Implementation Guide 1.1.0 context.

3rd party Apps using the confidential app profile are auto enabled if they are strictly a patient standalone app. A patient standalone app is one that only requests patient only scopes such as patient/*. A provider or system app (requesting permissions such as launch, user/*, system/*, etc) must be authorized by the eMedPractice Server Installation Administrator. Access Tokens issued to 3rd party apps are only valid for one hour and must be renewed with a refresh token which is valid for up to three months. Refresh tokens are only issued if the offline_access scope is authorized by the eMedPractice user authenticating with eMedPractice through their 3rd party app.

For a patient to have access to their patient data via a 3rd party app they must have api credentials generated by their clinician from the patient demographics page. A patient must not have opted out of 3rd party API access.

eMedPractice does NOT support wildcard scopes (patient/. or patient/*.read). Scopes must be requested explicitly by an app at the time of registration. eMedPractice does not support adding scopes from the initial registration.

Revoking Clients, Users, Access Tokens, Refresh Tokens

Revoking Clients

You can disable a client completely which prevents their access tokens from being used in the system from the Admin -> System -> API Clients interface. Edit the client registered in your system you wish to disable and hit the Disable button.

Revoking Users

If you wish to revoke a user's authorization for a particular client you will need to open up the API client from the Admin -> System -> API Clients interface. Once you are editing the client you will need to go to the Authenticated API Users section.

From there you can find the user that is listed and hit the Revoke User button (Note this can be a lengthy list so use your browser's search text functionality to find the user).

Revoking Access Tokens

You can revoke an access token two ways. One from the API Client edit screen, finding the client and then the access token's identifier you wish to revoke.

The second way is if you have the fully encoded access token using the API Client Tools screen. Go to Admin->System->API Clients and then click on the Token Tools button. Paste in the entire encoded token and then select Parse Token. Information about the token will be displayed including the authenticated user that authorized the token. Now select the Revoke Token button to revoke the token. A success message will be displayed when the revocation completes. You can parse the token again to see that the token has been revoked.

Native Applications

Interoperability requirements with eMedPractice for Native Applications

It is recommended that native applications follow best practices for native client applications as outlined in RFC 8252 OAuth 2.0 for Native Apps.

Carecoordination Summary of Care Docref Operation

Overview Docref

Details Docref

For Developers

FHIR endpoints are of the formats /fhir/r4/{resource} where resource can be patient, allergytolerance, condition etc. which maps to endpoint of the eMedPractice FHIR controller which handles the request, and also handles the JSON data conversions.

"GET /fhir/Patient" => function () {
        RestConfig::authorization_check("patients", "demo");
        $return = (newFhirPatientRestController())->getAll($_GET);
        RestConfig::apiLog($return);
        return$return;
    }

At a high level, the request processing flow consists of the following steps:

JSON Request -> FHIR Controller Component -> FHIR Validation -> Parsing FHIR Resource -> Standard Service Component -> Validation -> Database

The logical response flow begins with the database result:

Database Result -> Service Component -> FHIR Service Component -> Parse eMedPractice Record -> FHIR Controller Component -> RequestControllerHelper -> JSON Response

FHIR 4.0 New Registration

Click here for FHIR new registration.

Terms of use

Read and Accept the terms and conditions to use eMedPractice FHIR API 4.0. Click here for terms and conditions.