FHIR_README.md

   1 # OpenEMR FHIR API Documentation
   2
   3 ## FHIR API Table of Contents
   4 - [Overview](FHIR_README.md#overview)
   5 - [Prerequisite](FHIR_README.md#prerequisite)
   6 - [Using FHIR API Internally](FHIR_README.md#using-fhir-api-internally)
   7 - [Multisite Support](FHIR_README.md#multisite-support)
   8 - [Authorization (in API_README.md)](API_README.md#authorization)
   9     - [Scopes (in API_README.md)](API_README.md#scopes)
  10     - [Registration (in API_README.md)](API_README.md#registration)
  11         - [SMART on FHIR Registration (in API_README.md)](API_README.md#smart-on-fhir-registration)
  12     - [Authorization Code Grant (in API_README.md)](API_README.md#authorization-code-grant)
  13     - [Refresh Token Grant (in API_README.md)](API_README.md#refresh-token-grant)
  14     - [Password Grant (in API_README.md)](API_README.md#password-grant)
  15     - [Client Credentials Grant (in API_README.md)](API_README.md#client-credentials-grant)
  16     - [Logout (in API_README.md)](API_README.md#logout)
  17     - [More Details (in API_README.md)](API_README.md#more-details)
  18 - [FHIR API Documentation](FHIR_README.md#fhir-api-documentation)
  19     - [Capability Statement](FHIR_README.md#capability-statement)
  20     - [Provenance](FHIR_README.md#Provenance-resources)
  21     - [BULK FHIR Exports](FHIR_README.md#bulk-fhir-exports)
  22         - [System Export](FHIR_README.md#bulk-fhir-exports)
  23         - [Patient Export](FHIR_README.md#bulk-fhir-exports)
  24         - [Group Export](FHIR_README.md#bulk-fhir-exports)
  25 - [3rd Party SMART Apps](FHIR_README.md#3rd-party-smart-apps)
  26 - [Native Applications](FHIR_README.md#native-applications)
  27 - [For Developers](FHIR_README.md#for-developers)
  28
  29 ## Overview
  30
  31 Easy-to-use JSON-based REST API for OpenEMR FHIR. See standard OpenEMR API docs [here](API_README.md).  The OpenEMR FHIR API conforms to the R4 specification and the US Core 3.1 Implementation Guide (IG).
  32
  33 ## Prerequisite
  34
  35 Enable the Standard FHIR service (/fhir/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Standard FHIR REST API"
  36
  37 ## Using FHIR API Internally
  38
  39 There are several ways to make API calls from an authorized session and maintain security:
  40
  41 -   See the script at tests/api/InternalApiTest.php for examples of internal API use cases.
  42
  43 ## Multisite Support
  44
  45 Multisite is supported by including the site in the endpoint. When not using multisite or using the `default` multisite site, then a typical path would look like `apis/default/fhir/patient`. If you were using multisite and using a site called `alternate`, then the path would look like `apis/alternate/fhir/patient`.
  46
  47 ## Authorization
  48
  49 OpenEMR uses OIDC compliant authorization for API. SSL is required and setting baseurl at Administration->Globals->Connectors->'Site Address (required for OAuth2 and FHIR)' is required.
  50
  51 See [Authorization](API_README.md#authorization) for more details.
  52
  53 ## FHIR API Documentation
  54
  55 The FHIR API is documented via Swagger. Can see this documentation (and can test it) by going to the `swagger` directory in your OpenEMR installation. The FHIR API is documented there in the `fhir` section. Can also see (and test) this in the online demos at https://www.open-emr.org/wiki/index.php/Development_Demo#Daily_Build_Development_Demos (clicking on the `API (Swagger) User Interface` link for the demo will take you there).
  56
  57 Standard FHIR endpoints Use `https://localhost:9300/apis/default/fhir as base URI.`
  58
  59 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
  60
  61 _Example:_ `https://localhost:9300/apis/default/fhir/Patient` returns a Patient's bundle resource, etc
  62
  63 The Bearer token is required for each OpenEMR 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](API_README.md#authorization) section.
  64
  65 When registering an API client to use with Swagger the following for the redirect url and launch url for the client.
  66 - Redirect URL -> <base_site_address>/swagger/oauth2-redirect.html
  67 - Launch URL -> <base_site_address>/swagger/index.html
  68
  69 Request:
  70
  71 ```sh
  72 curl -X GET 'https://localhost:9300/apis/fhir/Patient' \
  73   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNnZ3eGJZYmFrOXlxUjF4U290Y1g4QVVDd3JOcG5yYXZEaFlqaHFjWXJXRGNDQUtFZmJONkh2cElTVkJiaWFobHBqOTBYZmlNRXpiY2FtU01pSHk1UzFlMmgxNmVqZEhcL1ZENlNtaVpTRFRLMmtsWDIyOFRKZzNhQmxMdUloZmNJM3FpMGFKZ003OXdtOGhYT3dpVkx5b3BFRXQ1TlNYNTE3UW5TZ0dsUVdQbG56WjVxOVYwc21tdDlSQ3RvcDV3TEkiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6ImZoaXIifQ=='
  74 ```
  75
  76 ---
  77
  78 ### Capability Statement
  79
  80 #### GET fhir/metadata
  81
  82 This will return the Capability Statement. Note this can be tested in the Swagger documentation linked to in the above `FHIR API Documentation`.
  83     ```sh
  84     curl -X GET 'https://localhost:9300/apis/default/fhir/metadata'
  85     ```
  86
  87 ### Provenance Resources
  88
  89 Provenance resources are requested by including `_revinclude=Provenance:target` in the search of a resource. Is currently supported for the following resources:
  90   - AllergyIntolerance
  91       ```sh
  92       curl -X GET 'https://localhost:9300/apis/default/fhir/AllergyIntolerance?_revinclude=Provenance:target'
  93       ```
  94
  95 ### BULK FHIR Exports
  96 An export operation that implements the [BULK FHIR Export ONC requirements](https://hl7.org/fhir/uv/bulkdata/export/index.html) can be requested by issuing a GET request to the following endpoints:
  97  - System Export, requires the **system/\*.$export** scope.  Exports All supported FHIR resources
  98     ```sh
  99           curl -X GET 'https://localhost:9300/apis/default/fhir/$export'
 100     ```
 101  - Group Export, requires the **system/Group.$export** scope.  Exports all data in the [Patient Compartment](https://www.hl7.org/fhir/compartmentdefinition-patient.html) for the group.
 102    The system automatically creates a group for every Practitioner resource in the system where the patients in the group are the individuals who have the Practitioner as their primary care provider.
 103     ```sh
 104           curl -X GET 'https://localhost:9300/apis/default/fhir/Group/1/$export'
 105     ```
 106  - Patient Export, requires the **system/Patient.$export** scope.  Exports all data for all patients in the [Patient Compartment](https://www.hl7.org/fhir/compartmentdefinition-patient.html).
 107     ```sh
 108           curl -X GET 'https://localhost:9300/apis/default/fhir/Patient/$export'
 109     ```
 110 You will get an empty body response with a **Content-Location** header with the URL you can query for status updates on the export.
 111
 112 To query the status update operation you need the **system/\*.$bulkdata-status** scope.  An example query:
 113  - Status Query
 114     ```sh
 115           curl -X GET 'https://localhost:9300/apis/default/fhir/$bulkdata-status?job=92a94c00-77d6-4dfc-ae3b-73550742536d'
 116     ```
 117
 118 A status Query will return a result like the following:
 119 ```
 120 {
 121   "transactionTime": {
 122     "date": "2021-02-05 20:48:38.000000",
 123     "timezone_type": 3,
 124     "timezone": "UTC"
 125   },
 126   "request": "\/apis\/default\/fhir\/Group\/1\/%24export",
 127   "requiresAccessToken": true,
 128   "output": [
 129     {
 130       "url": "https:\/\/localhost:9300\/apis\/default\/fhir\/Document\/97552\/Binary",
 131       "type": "Patient"
 132     },
 133     {
 134       "url": "https:\/\/localhost:9300\/apis\/default\/fhir\/Document\/105232\/Binary",
 135       "type": "Encounter"
 136     }
 137   ],
 138   "error": []
 139 }
 140 ```
 141
 142 You can download the exported documents which are formatted in Newline Delimited JSON (NDJSON) by making a call to:
 143     ```sh
 144           curl -X GET 'https://localhost:9300/apis/default/fhir/Document/105232/Binary'
 145     ```
 146
 147 In order to download the documents you will need the **system/Document.read** scope.
 148
 149 #### Bulk FHIR Scope Reference
 150 - All System export - **system/\*.$export system\*.$bulkdata-status system/Document.read**
 151 - Group System export - **system/Group.$export system\*.$bulkdata-status system/Document.read**
 152 - Patient System export - **system/Patient.$export system\*.$bulkdata-status system/Document.read**
 153
 154 ####
 155 ## 3rd Party SMART Apps
 156 OpenEMR supports the ability for 3rd party apps who implement the [SMART on FHIR App Launch Implementation Guide 1.1.0](http://hl7.org/fhir/smart-app-launch/2021May/) context.
 157
 158 3rd party Apps using the confidential app profile must be authorized by the OpenEMR 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 OpenEMR user authenticating with OpenEMR through their 3rd party app.
 159
 160 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.
 161
 162 OpenEMR does NOT support wildcard scopes (patient/*.* or patient/*.read).  Scopes must be requested explicitly by an app at the time of registration.  OpenEMR does not support adding scopes from the initial registration.
 163
 164
 165 ## Revoking Clients, Users, Access Tokens, Refresh Tokens
 166
 167 ## Revoking Clients
 168 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.
 169
 170 ## Revoking Users
 171 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.
 172
 173 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).
 174
 175 ## Revoking Access Tokens
 176 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.
 177
 178 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.
 179
 180 ## Native Applications
 181 Interoperability requirements with OpenEMR for Native Applications
 182
 183 - Native applications wishing to use the OpenEMR FHIR API with refresh tokens MUST be capable of storing the refresh token in a secure manner similar to the requirements of storing a secret for confidential apps.
 184 - Native applications must register their application as a confidential app
 185 - Native applications must request the offline_scope in their initial API request in order to receive a refresh token
 186 - Native application refresh tokens are valid for 3 months before they must be renewed.
 187 - Native applications can only communicate with OpenEMR over a TLS secured channel in order to ensure the safe transmission of the refresh token.
 188 - Native applications must use the Authorization Code grant flow in order to receive a refresh token.
 189
 190 It is recommended that native applications follow best practices for native client applications as outlined in RFC 8252 OAuth 2.0 for Native Apps.
 191
 192 ## For Developers
 193
 194 FHIR endpoints are defined in the [primary routes file](_rest_routes.inc.php). The routes file maps an external, addressable
 195 endpoint to the OpenEMR FHIR controller which handles the request, and also handles the JSON data conversions.
 196
 197 ```php
 198 "GET /fhir/Patient" => function () {
 199     RestConfig::authorization_check("patients", "demo");
 200     $return = (new FhirPatientRestController())->getAll($_GET);
 201     RestConfig::apiLog($return);
 202     return $return;
 203 }
 204 ```
 205
 206 At a high level, the request processing flow consists of the following steps:
 207
 208 ```
 209 JSON Request -> FHIR Controller Component -> FHIR Validation -> Parsing FHIR Resource -> Standard Service Component -> Validation -> Database
 210 ```
 211
 212 The logical response flow begins with the database result:
 213
 214 ```
 215 Database Result -> Service Component -> FHIR Service Component -> Parse OpenEMR Record -> FHIR Controller Component -> RequestControllerHelper -> JSON Response
 216 ```
 217