API_README.md

   1 # OpenEMR REST API Documentation
   2
   3 ## REST API Table of Contents
   4 - [Overview](API_README.md#overview)
   5 - [Prerequisite](API_README.md#prerequisite)
   6 - [Using API Internally](API_README.md#using-api-internally)
   7 - [Multisite Support](API_README.md#multisite-support)
   8 - [Authorization](API_README.md#authorization)
   9     - [Scopes](API_README.md#scopes)
  10     - [Registration](API_README.md#registration)
  11         - [SMART on FHIR Registration](API_README.md#smart-on-fhir-registration)
  12     - [Authorization Code Grant](API_README.md#authorization-code-grant)
  13     - [Refresh Token Grant](API_README.md#refresh-token-grant)
  14     - [Password Grant](API_README.md#password-grant)
  15     - [Client Credentials Grant](API_README#client-credentials-grant)
  16     - [Logout](API_README.md#logout)
  17     - [More Details](API_README.md#more-details)
  18 - [Standard API Documentation](API_README.md#standard-api-documentation)
  19 - [Patient Portal API Documentation](API_README.md#patient-portal-api-documentation)
  20 - [FHIR API Documentation (in FHIR_README.md)](FHIR_README.md#fhir-api-documentation)
  21     - [Capability Statement (in FHIR_README.md)](FHIR_README.md#capability-statement)
  22     - [Provenance (in FHIR_README.md)](FHIR_README.md#Provenance-resources)
  23     - [BULK FHIR Exports (in FHIR_README.md)](FHIR_README.md#bulk-fhir-exports)
  24         - [System Export (in FHIR_README.md)](FHIR_README.md#bulk-fhir-exports)
  25         - [Patient Export (in FHIR_README.md)](FHIR_README.md#bulk-fhir-exports)
  26         - [Group Export (in FHIR_README.md)](FHIR_README.md#bulk-fhir-exports)
  27     - [3rd Party SMART Apps (in FHIR_README.md)](FHIR_README.md#3rd-party-smart-apps)
  28     - [Native Applications (in FHIR_README.md)](FHIR_README.md#native-applications)
  29     - [Carecoordination Summary of Care (CCD) Generation (in FHIR_README.md)](FHIR_README.md#carecoordination-summary-of-care-docref-operation)
  30         - [Overview Docref (in FHIR_README.md)](FHIR_README.md#overview-docref)
  31         - [Generate CCDA (in FHIR_README.md)](FHIR_README.md#generate-ccda)
  32         - [Details Docref (in FHIR_README.md)](FHIR_README.md#details-docref)
  33 - [Security Settings](API_README.md#security)
  34 - [For Developers](API_README.md#for-developers)
  35
  36 ## Overview
  37
  38 Easy-to-use JSON-based REST API for OpenEMR. FHIR is also supported, see FHIR API documentation [here](FHIR_README.md),
  39
  40 ## Prerequisite
  41
  42 Enable the Standard API service (/api/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Standard REST API"
  43
  44 ## Using API Internally
  45
  46 There are several ways to make API calls from an authorized session and maintain security:
  47
  48 -   See the script at tests/api/InternalApiTest.php for examples of internal API use cases.
  49
  50 ## Multisite Support
  51
  52 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/api/patient`. If you are using multisite and using a site called `alternate`, then the path would look like `apis/alternate/api/patient`.
  53
  54 ## Authorization
  55
  56 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. The listing of scopes can be found in below Scopes section.
  57
  58 ### Scopes
  59
  60 This is a listing of scopes:
  61 - `openid` (Generic mandatory scope)
  62 - `fhirUser`
  63 - `online_access`
  64 - `offline_access` (Will signal server to provide a refresh token)
  65 - `launch`
  66 - `launch/patient`
  67 - `api:fhir` (fhir which are the /fhir/ endpoints)
  68   - `patient/AllergyIntolerance.read`
  69   - `patient/Appointment.read`
  70   - `patient/Binary.read`
  71   - `patient/CarePlan.read`
  72   - `patient/CareTeam.read`
  73   - `patient/Condition.read`
  74   - `patient/Coverage.read`
  75   - `patient/Device.read`
  76   - `patient/DiagnosticReport.read`
  77   - `patient/DocumentReference.read`
  78   - `patient/DocumentReference.$docref`
  79   - `patient/Encounter.read`
  80   - `patient/Goal.read`
  81   - `patient/Immunization.read`
  82   - `patient/Location.read`
  83   - `patient/MedicationRequest.read`
  84   - `patient/Medication.read`
  85   - `patient/Observation.read`
  86   - `patient/Organization.read`
  87   - `patient/Patient.read`
  88   - `patient/Person.read`
  89   - `patient/Practitioner.read`
  90   - `patient/Procedure.read`
  91   - `patient/Provenance.read`
  92   - `system/AllergyIntolerance.read`
  93   - `system/Binary.read`
  94   - `system/CarePlan.read`
  95   - `system/CareTeam.read`
  96   - `system/Condition.read`
  97   - `system/Coverage.read`
  98   - `system/Device.read`
  99   - `system/DiagnosticReport.read`
 100   - `system/DocumentReference.read`
 101   - `system/DocumentReference.$docref`
 102   - `system/Encounter.read`
 103   - `system/Goal.read`
 104   - `system/Group.read`
 105   - `system/Group.$export`
 106   - `system/Immunization.read`
 107   - `system/Location.read`
 108   - `system/MedicationRequest.read`
 109   - `system/Medication.read`
 110   - `system/Observation.read`
 111   - `system/Organization.read`
 112   - `system/Patient.read`
 113   - `system/Patient.$export`
 114   - `system/Person.read`
 115   - `system/Practitioner.read`
 116   - `system/PractitionerRole.read`
 117   - `system/Procedure.read`
 118   - `system/Provenance.read`
 119   - `system/*.$bulkdata-status`
 120   - `system/*.$export`
 121   - `user/AllergyIntolerance.read`
 122   - `user/Binary.read`
 123   - `user/CarePlan.read`
 124   - `user/CareTeam.read`
 125   - `user/Condition.read`
 126   - `user/Coverage.read`
 127   - `user/Device.read`
 128   - `user/DiagnosticReport.read`
 129   - `user/DocumentReference.read`
 130   - `user/DocumentReference.$docref`
 131   - `user/Encounter.read`
 132   - `user/Goal.read`
 133   - `user/Immunization.read`
 134   - `user/Location.read`
 135   - `user/MedicationRequest.read`
 136   - `user/Medication.read`
 137   - `user/Observation.read`
 138   - `user/Organization.read`
 139   - `user/Organization.write`
 140   - `user/Patient.read`
 141   - `user/Patient.write`
 142   - `user/Person.read`
 143   - `user/Practitioner.read`
 144   - `user/Practitioner.write`
 145   - `user/PractitionerRole.read`
 146   - `user/Procedure.read`
 147   - `user/Provenance.read`
 148 - `api:oemr` (user api which are the /api/ endpoints)
 149   - `user/allergy.read`
 150   - `user/allergy.write`
 151   - `user/appointment.read`
 152   - `user/appointment.write`
 153   - `user/dental_issue.read`
 154   - `user/dental_issue.write`
 155   - `user/document.read`
 156   - `user/document.write`
 157   - `user/drug.read`
 158   - `user/encounter.read`
 159   - `user/encounter.write`
 160   - `user/facility.read`
 161   - `user/facility.write`
 162   - `user/immunization.read`
 163   - `user/insurance.read`
 164   - `user/insurance.write`
 165   - `user/insurance_company.read`
 166   - `user/insurance_company.write`
 167   - `user/insurance_type.read`
 168   - `user/list.read`
 169   - `user/medical_problem.read`
 170   - `user/medical_problem.write`
 171   - `user/medication.read`
 172   - `user/medication.write`
 173   - `user/message.write`
 174   - `user/patient.read`
 175   - `user/patient.write`
 176   - `user/practitioner.read`
 177   - `user/practitioner.write`
 178   - `user/prescription.read`
 179   - `user/procedure.read`
 180   - `user/soap_note.read`
 181   - `user/soap_note.write`
 182   - `user/surgery.read`
 183   - `user/surgery.write`
 184   - `user/transaction.read`
 185   - `user/transaction.write`
 186   - `user/vital.read`
 187   - `user/vital.write`
 188 - `api:port` (patient api which are the /portal/ endpoints) (EXPERIMENTAL)
 189   - `patient/encounter.read`
 190   - `patient/patient.read`
 191   - `patient/appointment.read`
 192
 193 ### Registration
 194
 195 Here is an example for registering a client. A client needs to be registered before applying for grant to obtain access/refresh tokens. Note: "post_logout_redirect_uris" is optional and only used if client wants a redirect to its own confirmation workflow.
 196
 197 Note that all scopes are included in this example for demonstration purposes. For production purposes, should only include the necessary scopes.
 198
 199 ```sh
 200 curl -X POST -k -H 'Content-Type: application/json' -i https://localhost:9300/oauth2/default/registration --data '{
 201    "application_type": "private",
 202    "redirect_uris":
 203      ["https://client.example.org/callback"],
 204    "post_logout_redirect_uris":
 205      ["https://client.example.org/logout/callback"],
 206    "client_name": "A Private App",
 207    "token_endpoint_auth_method": "client_secret_post",
 208    "contacts": ["me@example.org", "them@example.org"],
 209    "scope": "openid offline_access api:oemr api:fhir api:port user/allergy.read user/allergy.write user/appointment.read user/appointment.write user/dental_issue.read user/dental_issue.write user/document.read user/document.write user/drug.read user/encounter.read user/encounter.write user/facility.read user/facility.write user/immunization.read user/insurance.read user/insurance.write user/insurance_company.read user/insurance_company.write user/insurance_type.read user/list.read user/medical_problem.read user/medical_problem.write user/medication.read user/medication.write user/message.write user/patient.read user/patient.write user/practitioner.read user/practitioner.write user/prescription.read user/procedure.read user/soap_note.read user/soap_note.write user/surgery.read user/surgery.write user/transaction.read user/transaction.write user/vital.read user/vital.write user/AllergyIntolerance.read user/CareTeam.read user/Condition.read user/Coverage.read user/Encounter.read user/Immunization.read user/Location.read user/Medication.read user/MedicationRequest.read user/Observation.read user/Organization.read user/Organization.write user/Patient.read user/Patient.write user/Practitioner.read user/Practitioner.write user/PractitionerRole.read user/Procedure.read patient/encounter.read patient/patient.read patient/AllergyIntolerance.read patient/CareTeam.read patient/Condition.read patient/Coverage.read patient/Encounter.read patient/Immunization.read patient/MedicationRequest.read patient/Observation.read patient/Patient.read patient/Procedure.read"
 210   }'
 211 ```
 212
 213 Response:
 214 ```sh
 215 {
 216     "client_id": "LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA",
 217     "client_secret": "j21ecvLmFi9HPc_Hv0t7Ptmf1pVcZQLtHjIdU7U9tkS9WAjFJwVMav0G8ogTJ62q4BATovC7BQ19Qagc4x9BBg",
 218     "registration_access_token": "uiDSXx2GNSvYy5n8eW50aGrJz0HjaGpUdrGf07Agv_Q",
 219     "registration_client_uri": "https:\/\/localhost:9300\/oauth2\/default\/client\/6eUVG0-qK2dYiwfYdECKIw",
 220     "client_id_issued_at": 1604767861,
 221     "client_secret_expires_at": 0,
 222     "contacts": ["me@example.org", "them@example.org"],
 223     "application_type": "private",
 224     "client_name": "A Private App",
 225     "redirect_uris": ["https:\/\/client.example.org\/callback"],
 226     "token_endpoint_auth_method": "client_secret_post",
 227     "scope": "openid offline_access api:oemr api:fhir api:port user/allergy.read user/allergy.write user/appointment.read user/appointment.write user/dental_issue.read user/dental_issue.write user/document.read user/document.write user/drug.read user/encounter.read user/encounter.write user/facility.read user/facility.write user/immunization.read user/insurance.read user/insurance.write user/insurance_company.read user/insurance_company.write user/insurance_type.read user/list.read user/medical_problem.read user/medical_problem.write user/medication.read user/medication.write user/message.write user/patient.read user/patient.write user/practitioner.read user/practitioner.write user/prescription.read user/procedure.read user/soap_note.read user/soap_note.write user/surgery.read user/surgery.write  user/transaction.read user/transaction.write user/vital.read user/vital.write user/AllergyIntolerance.read user/CareTeam.read user/Condition.read user/Coverage.read user/Encounter.read user/Immunization.read user/Location.read user/Medication.read user/MedicationRequest.read user/Observation.read user/Organization.read user/Organization.write user/Patient.read user/Patient.write user/Practitioner.read user/Practitioner.write user/PractitionerRole.read user/Procedure.read patient/encounter.read patient/patient.read patient/AllergyIntolerance.read patient/CareTeam.read patient/Condition.read patient/Coverage.read patient/Encounter.read patient/Immunization.read patient/MedicationRequest.read patient/Observation.read patient/Patient.read patient/Procedure.read"
 228 }
 229 ```
 230
 231 #### SMART on FHIR Registration
 232
 233 SMART Enabled Apps are supported.
 234
 235 SMART client can be registered at <website>/interface/smart/register-app.php. For example https://localhost:9300/interface/smart/register-app.php
 236
 237 After registering the SMART client, can then Enable it in OpenEMR at Administration->System->API Clients
 238
 239 After it is enabled, the SMART App will then be available to use in the Patient Summary screen (SMART Enabled Apps widget).
 240
 241 See this github issue for an example of a Smart App installation: https://github.com/openemr/openemr/issues/4148
 242
 243 ### Authorization Code Grant
 244
 245 This is the recommended standard mechanism to obtain access/refresh tokens. This is done by using an OAuth2 client with provider url of `oauth2/<site>`; an example full path would be `https://localhost:9300/oauth2/default`.  Standard OAUTH2 clients will retrieve the authorize URL from the FHIR /metadata endpoint, but if you are building your own client you can access the metadata or go directly to the https://localhost:9300/oauth2/default/authorize endpoint.
 246
 247 Note that a refresh token is only supplied if the `offline_access` scope is provided when requesting authorization grant.
 248
 249 You will need to pass the scopes you are requesting, the redirect_uri (must be one that was registered at the time of your client registration), and a state parameter which can be any value.  Once authorization has finished the browser will be redirected to the URL specified in redirect_uri with an encrypted code value and the state value sent in the initial authorize request.
 250
 251 Example GET (this must be done in a browser):
 252 ```
 253 GET /oauth2/default/authorize?client_id=yi4mnmVadpnqnJiOigkcGshuG-Kayiq6kmLqCJsYrk4&response_type=code&scope=launch%2Fpatient%20openid%20fhirUser%20offline_access%20patient%2FAllergyIntolerance.read%20patient%2FCarePlan.read%20patient%2FCareTeam.read%20patient%2FCondition.read%20patient%2FDevice.read%20patient%2FDiagnosticReport.read%20patient%2FDocumentReference.read%20patient%2FEncounter.read%20patient%2FGoal.read%20patient%2FImmunization.read%20patient%2FLocation.read%20patient%2FMedication.read%20patient%2FMedicationRequest.read%20patient%2FObservation.read%20patient%2FOrganization.read%20patient%2FPatient.read%20patient%2FPractitioner.read%20patient%2FProcedure.read%20patient%2FProvenance.read&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback&state=9512151b-e5ca-cb4b-1ddc-aaf4cd8c6ecc
 254 ```
 255
 256 The client application must then make a request for an access token by hitting the /token endpoint.  Note the redirect_uri MUST match what what was sent in /authorize endpoint.  If your application is registered as a public application you must include the client_id in the POST request.  If you are registered as a confidential app you must use HTTP Basic Authentication where the client_id is your username and the password is your client_secret.  HTTP Basic Authentication follows the algorithm of base64_encode(username:client_secret).  In PHP this would be base64_encode($client_id . ':' . $client_secret);  Note that this mechanism should ONLY be used over an encrypted protocol such as TLS to prevent leaking your client_secret.
 257
 258 Example Public Application POST
 259 ```
 260 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 261 'https://localhost:9300/oauth2/default/token'
 262 --data 'grant_type=authorization_code&client_id=yi4mnmVadpnqnJiOigkcGshuG-Kayiq6kmLqCJsYrk4redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback&code=def50...'
 263 ```
 264
 265 Example Private Application POST
 266 ```
 267 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' \
 268     -H 'Authorization: Basic c3Z2TThFX1hISEhYUmtoZzUyeWoyNjdIOEYwQnpmT09pRmE4aUZBT290WTptbzZpZEFPaEU0UVYxb0lacUR5YTFHR1JHVGU5VDQzNWpzeTlRbWYxV2NiVFQ4NXhuZW5VdUpaUFR0bUZGT1QxVkhmYjZiclVvWWZ2Znd2NTFQejFldw==' \
 269     'https://localhost:9300/oauth2/default/token' \
 270     --data 'grant_type=authorization_code&client_id=yi4mnmVadpnqnJiOigkcGshuG-Kayiq6kmLqCJsYrk4redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback&code=def50...'
 271 ```
 272 ### Refresh Token Grant
 273
 274 Note that a refresh token is only supplied if the `offline_access` scope is provided when requesting authorization or password grant.
 275
 276 Example:
 277
 278 ```sh
 279 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 280 -i 'https://localhost:9300/oauth2/default/token'
 281 --data 'grant_type=refresh_token
 282 &client_id=LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA
 283 &refresh_token=def5020089a766d16...'
 284 ```
 285
 286 Response:
 287
 288 ```json
 289 {
 290   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYn...",
 291   "token_type": "Bearer",
 292   "expires_in": 3599,
 293   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYnl1RkRp...",
 294   "refresh_token": "def5020017b484b0add020bf3491a8a537fa04eda12..."
 295 }
 296 ```
 297
 298 ### Password Grant
 299
 300 Recommend not using this mechanism unless you know what you are doing. It is considered far less secure than the standard authorization code method. Because of security implications, it is not turned on by default. It can be turned on at Administration->Globals->Connectors->'Enable OAuth2 Password Grant (Not considered secure)'.
 301
 302 Note that all scopes are included in these examples for demonstration purposes. For production purposes, should only include the necessary scopes.
 303
 304 Note that a refresh token is only supplied if the `offline_access` scope is provided when requesting password grant.
 305
 306 Example for `users` role:
 307 ```sh
 308 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 309 -i 'https://localhost:9300/oauth2/default/token'
 310 --data 'grant_type=password
 311 &client_id=LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA
 312 &scope=openid%20offline_access%20api%3Aoemr%20api%3Afhir%20user%2Fallergy.read%20user%2Fallergy.write%20user%2Fappointment.read%20user%2Fappointment.write%20user%2Fdental_issue.read%20user%2Fdental_issue.write%20user%2Fdocument.read%20user%2Fdocument.write%20user%2Fdrug.read%20user%2Fencounter.read%20user%2Fencounter.write%20user%2Ffacility.read%20user%2Ffacility.write%20user%2Fimmunization.read%20user%2Finsurance.read%20user%2Finsurance.write%20user%2Finsurance_company.read%20user%2Finsurance_company.write%20user%2Finsurance_type.read%20user%2Flist.read%20user%2Fmedical_problem.read%20user%2Fmedical_problem.write%20user%2Fmedication.read%20user%2Fmedication.write%20user%2Fmessage.write%20user%2Fpatient.read%20user%2Fpatient.write%20user%2Fpractitioner.read%20user%2Fpractitioner.write%20user%2Fprescription.read%20user%2Fprocedure.read%20user%2Fsoap_note.read%20user%2Fsoap_note.write%20user%2Fsurgery.read%20user%2Fsurgery.write%20user%2Ftransaction.read%20user%2Ftransaction.write%20user%2Fvital.read%20user%2Fvital.write%20user%2FAllergyIntolerance.read%20user%2FCareTeam.read%20user%2FCondition.read%20user%2FCoverage.read%20user%2FEncounter.read%20user%2FImmunization.read%20user%2FLocation.read%20user%2FMedication.read%20user%2FMedicationRequest.read%20user%2FObservation.read%20user%2FOrganization.read%20user%2FOrganization.write%20user%2FPatient.read%20user%2FPatient.write%20user%2FPractitioner.read%20user%2FPractitioner.write%20user%2FPractitionerRole.read%20user%2FProcedure.read
 313 &user_role=users
 314 &username=admin
 315 &password=pass'
 316 ```
 317
 318 Example for `patient` role:
 319 ```sh
 320 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 321 -i 'https://localhost:9300/oauth2/default/token'
 322 --data 'grant_type=password
 323 &client_id=LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA
 324 &scope=openid%20offline_access%20api%3Aport%20api%3Afhir%20patient%2Fencounter.read%20patient%2Fpatient.read%20patient%2FAllergyIntolerance.read%20patient%2FCareTeam.read%20patient%2FCondition.read%20patient%2FCoverage.read%20patient%2FEncounter.read%20patient%2FImmunization.read%20patient%2FMedication.read%20patient%2FMedicationRequest.read%20patient%2FObservation.read%20patient%2FPatient.read%20patient%2FProcedure.read
 325 &user_role=patient
 326 &username=Phil1
 327 &password=phil
 328 &email=heya@invalid.email.com'
 329 ```
 330
 331 Response:
 332
 333 ```json
 334 {
 335   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYn...",
 336   "token_type": "Bearer",
 337   "expires_in": 3599,
 338   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYnl1RkRp...",
 339   "refresh_token": "def5020017b484b0add020bf3491a8a537fa04eda12..."
 340 }
 341 ```
 342
 343 ### Client Credentials Grant
 344
 345 This is an advanced grant that uses JSON Web Key Sets(JWKS) to authenticate and identify the client.  This credential grant is
 346 required to be used for access to any **system/\*.$export** scopes.  API clients must register either web accessible JWKS URI that hosts
 347 a RSA384 compatible key, or provide their JWKS as part of the registration. Client Credentials Grant access tokens are short
 348 lived and valid for only 1 minute and no refresh token is issued.  Tokens are requested at `/oauth2/default/token`
 349 To walk you through how to do this process you can follow [this guide created by HL7](https://hl7.org/fhir/uv/bulkdata/authorization/index.html).
 350
 351 ### Logout
 352
 353 A grant (both Authorization Code and Password grants) can be logged out (ie. removed) by url of `oauth2/<site>/logout?id_token_hint=<id_token>`; an example full path would be `https://localhost:9300/oauth2/default/logout?id_token_hint=<id_token>`. Optional: `post_logout_redirect_uri` and `state` parameters can also be sent; note that `post_logout_redirect_uris` also needs to be set during registration for it to work.
 354
 355 ### More Details
 356
 357 The forum thread that detailed development of Authorization and where questions and issues are addressed is here: https://community.open-emr.org/t/v6-authorization-and-api-changes-afoot/15450
 358
 359 More specific development api topics are discussed and described on the above forum thread (such as introspection).
 360
 361 ## Standard API Documentation
 362
 363 The Standard API is documented via Swagger. Can see this documentation (and can test it) by going to the `swagger` directory in your OpenEMR installation. The Standard API is documented there in the `standard` 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).  Make sure to set your client api registration's redirect_uris to be `<OpenEMR base URI>/swagger/oauth2-redirect.html`.
 364
 365 OpenEMR standard endpoints Use `https://localhost:9300/apis/default/api as base URI.`
 366
 367 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
 368
 369 _Example:_ `https://localhost:9300/apis/default/api/patient` returns a resource of all Patients.
 370
 371 The Bearer token is required for each OpenEMR API request, and is conveyed using an Authorization header. Note that the Bearer token is the access_token that is obtained in the above [Authorization](API_README.md#authorization) section.
 372
 373 Request:
 374
 375 ```sh
 376 curl -X GET 'https://localhost:9300/apis/default/api/patient/1/medical_problem' \
 377   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
 378 ```
 379
 380 ## Patient Portal API Documentation
 381
 382 The Patient Portal API is documented via Swagger. Can see this documentation (and can test it) by going to the `swagger` directory in your OpenEMR installation. The Patient Portal API is documented there in the `standard-patient` 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). Make sure to set your client api registration's redirect_uris to be `<OpenEMR base URI>/swagger/oauth2-redirect.html`.
 383
 384 This is under development and is considered EXPERIMENTAL.
 385
 386 Enable the Patient Portal API service (/portal/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Patient Portal REST API (EXPERIMENTAL)"
 387
 388 OpenEMR patient portal endpoints Use `https://localhost:9300/apis/default/portal as base URI.`
 389
 390 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
 391
 392 _Example:_ `https://localhost:9300/apis/default/portal/patient` returns a resource of the patient.
 393
 394 The Bearer token is required for each OpenEMR API request, and is conveyed using an Authorization header. Note that the Bearer token is the access_token that is obtained in the above [Authorization](API_README.md#authorization) section.
 395
 396 Request:
 397
 398 ```sh
 399 curl -X GET 'https://localhost:9300/apis/default/portal/patient' \
 400   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
 401 ```
 402
 403 ## Security
 404 - OpenEMR adminstrators / installers should ensure that the API is protected using an end to end encryption protocol such as TLS
 405 - Password Grant SHOULD be turned off for any kind of production use as it has a number of security problems
 406 - Setting the Admin -> Globals -> OAuth2 App Manual Approval Settings to be 'Manual Approval' prevents any OAuth2 application from accessing the API without manual approval from an administrator.  This is the most secure setting.  However, in the USA jurisdiction that must comply with CEHRT rules for ONC 2015 Cures Update, patient standalone apps must be approved within 48 hours of a patient requesting access in order to avoid pentalities under the Information Blocking Provisions from ONC.  EHR administrators are not allowed to vet a patient's choice of an app as long as the app complies with OpenEMR's OAuth2 security requirements.  If an app requests user/* or system/* scopes, administrators can vet an application and request additional information / security on an app by app basis.  Leaving the setting at the default will auto-approve any patient standalone app.
 407 - Public apps (ones that can't securely store a secret) MUST implement the PKCE standard specified in [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636).  Confidential apps are still highly encouraged to implement PKCE to mitigate forms of MITM attacks such as multiple native app devices registering for the same custom url scheme used as the OAUTH2 redirect_uri in the authorization_code grant.
 408
 409 ## For Developers
 410
 411 -   For business logic, make or use the services [here](src/Services)
 412 -   For controller logic, make or use the classes [here](src/RestControllers)
 413 -   For routing declarations, use the class [here](_rest_routes.inc.php).
 414
 415 REST API endpoints are defined in the [primary routes file](_rest_routes.inc.php). The routes file maps an external, addressable
 416 endpoint to the OpenEMR controller which handles the request, and also handles the JSON data conversions.
 417
 418 ```php
 419 "POST /api/patient" => function () {
 420     RestConfig::authorization_check("patients", "demo");
 421     $data = (array) (json_decode(file_get_contents("php://input")));
 422     $return = (new PatientRestController())->post($data);
 423     RestConfig::apiLog($return, $data);
 424     return $return;
 425 }
 426 ```
 427
 428 At a high level, the request processing flow consists of the following steps:
 429
 430 ```
 431 JSON Request -> Controller Component -> Validation -> Service Component -> Database
 432 ```
 433
 434 The logical response flow begins with the database result:
 435
 436 ```
 437 Database Result -> Service Component -> Controller Component -> RequestControllerHelper -> JSON Response
 438 ```
 439
 440 The [RequestControllerHelper class](./src/RestControllers/RestControllerHelper.php) evaluates the Service Component's
 441 result and maps it to a http response code and response payload. Existing APIs should be updated to utilize the
 442 `handleProcessingResult` method as it supports the [Validator](./src/Validators/BaseValidator.php) components.
 443
 444 The [PatientRestController](./src/RestControllers/PatientRestController.php) may be used as a reference to see how APIs are
 445 integrated with `RequestControllerHelper::handleProcessingResult` and the `Validator` components.
 446
 447 Finally, APIs which are integrated with the new `handleProcessingResult` method utilize a common response format.
 448
 449 ```json
 450 {
 451     "validationErrors": [],
 452     "internalErrors": [],
 453     "data": < data payload >
 454 }
 455 ```
 456
 457 -   `validationErrors` contain "client based" data validation errors
 458 -   `internalErrors` contain server related errors
 459 -   `data` is the response payload, represented as an object/`{}` for single results or an array/`[]` for multiple results