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 - [For Developers](API_README.md#for-developers)
  34
  35 ## Overview
  36
  37 Easy-to-use JSON-based REST API for OpenEMR. FHIR is also supported, see FHIR API documentation [here](FHIR_README.md),
  38
  39 ## Prerequisite
  40
  41 Enable the Standard API service (/api/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Standard REST API"
  42
  43 ## Using API Internally
  44
  45 There are several ways to make API calls from an authorized session and maintain security:
  46
  47 -   See the script at tests/api/InternalApiTest.php for examples of internal API use cases.
  48
  49 ## Multisite Support
  50
  51 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`.
  52
  53 ## Authorization
  54
  55 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.
  56
  57 ### Scopes
  58
  59 This is a listing of scopes:
  60 - `openid` (Generic mandatory scope)
  61 - `fhirUser`
  62 - `online_access`
  63 - `offline_access` (Will signal server to provide a refresh token)
  64 - `launch`
  65 - `launch/patient`
  66 - `api:fhir` (fhir which are the /fhir/ endpoints)
  67   - `patient/AllergyIntolerance.read`
  68   - `patient/CarePlan.read`
  69   - `patient/CareTeam.read`
  70   - `patient/Condition.read`
  71   - `patient/Coverage.read`
  72   - `patient/Device.read`
  73   - `patient/DiagnosticReport.read`
  74   - `patient/Document.read`
  75   - `patient/DocumentReference.read`
  76   - `patient/DocumentReference.$docref`
  77   - `patient/Encounter.read`
  78   - `patient/Goal.read`
  79   - `patient/Immunization.read`
  80   - `patient/Location.read`
  81   - `patient/MedicationRequest.read`
  82   - `patient/Medication.read`
  83   - `patient/Observation.read`
  84   - `patient/Organization.read`
  85   - `patient/Patient.read`
  86   - `patient/Person.read`
  87   - `patient/Practitioner.read`
  88   - `patient/Procedure.read`
  89   - `patient/Provenance.read`
  90   - `system/AllergyIntolerance.read`
  91   - `system/CarePlan.read`
  92   - `system/CareTeam.read`
  93   - `system/Condition.read`
  94   - `system/Coverage.read`
  95   - `system/Device.read`
  96   - `system/DiagnosticReport.read`
  97   - `system/Document.read`
  98   - `system/DocumentReference.read`
  99   - `system/DocumentReference.$docref`
 100   - `system/Encounter.read`
 101   - `system/Goal.read`
 102   - `system/Group.read`
 103   - `system/Group.$export`
 104   - `system/Immunization.read`
 105   - `system/Location.read`
 106   - `system/MedicationRequest.read`
 107   - `system/Medication.read`
 108   - `system/Observation.read`
 109   - `system/Organization.read`
 110   - `system/Patient.read`
 111   - `system/Patient.$export`
 112   - `system/Person.read`
 113   - `system/Practitioner.read`
 114   - `system/PractitionerRole.read`
 115   - `system/Procedure.read`
 116   - `system/Provenance.read`
 117   - `system/*.$bulkdata-status`
 118   - `system/*.$export`
 119   - `user/AllergyIntolerance.read`
 120   - `user/CarePlan.read`
 121   - `user/CareTeam.read`
 122   - `user/Condition.read`
 123   - `user/Coverage.read`
 124   - `user/Device.read`
 125   - `user/DiagnosticReport.read`
 126   - `user/Document.read`
 127   - `user/DocumentReference.read`
 128   - `user/DocumentReference.$docref`
 129   - `user/Encounter.read`
 130   - `user/Goal.read`
 131   - `user/Immunization.read`
 132   - `user/Location.read`
 133   - `user/MedicationRequest.read`
 134   - `user/Medication.read`
 135   - `user/Observation.read`
 136   - `user/Organization.read`
 137   - `user/Organization.write`
 138   - `user/Patient.read`
 139   - `user/Patient.write`
 140   - `user/Person.read`
 141   - `user/Practitioner.read`
 142   - `user/Practitioner.write`
 143   - `user/PractitionerRole.read`
 144   - `user/Procedure.read`
 145   - `user/Provenance.read`
 146 - `api:oemr` (user api which are the /api/ endpoints)
 147   - `user/allergy.read`
 148   - `user/allergy.write`
 149   - `user/appointment.read`
 150   - `user/appointment.write`
 151   - `user/dental_issue.read`
 152   - `user/dental_issue.write`
 153   - `user/document.read`
 154   - `user/document.write`
 155   - `user/drug.read`
 156   - `user/encounter.read`
 157   - `user/encounter.write`
 158   - `user/facility.read`
 159   - `user/facility.write`
 160   - `user/immunization.read`
 161   - `user/insurance.read`
 162   - `user/insurance.write`
 163   - `user/insurance_company.read`
 164   - `user/insurance_company.write`
 165   - `user/insurance_type.read`
 166   - `user/list.read`
 167   - `user/medical_problem.read`
 168   - `user/medical_problem.write`
 169   - `user/medication.read`
 170   - `user/medication.write`
 171   - `user/message.write`
 172   - `user/patient.read`
 173   - `user/patient.write`
 174   - `user/practitioner.read`
 175   - `user/practitioner.write`
 176   - `user/prescription.read`
 177   - `user/procedure.read`
 178   - `user/soap_note.read`
 179   - `user/soap_note.write`
 180   - `user/surgery.read`
 181   - `user/surgery.write`
 182   - `user/transaction.read`
 183   - `user/transaction.write`
 184   - `user/vital.read`
 185   - `user/vital.write`
 186 - `api:port` (patient api which are the /portal/ endpoints) (EXPERIMENTAL)
 187   - `patient/encounter.read`
 188   - `patient/patient.read`
 189
 190 ### Registration
 191
 192 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.
 193
 194 Note that all scopes are included in this example for demonstration purposes. For production purposes, should only include the necessary scopes.
 195
 196 ```sh
 197 curl -X POST -k -H 'Content-Type: application/json' -i https://localhost:9300/oauth2/default/registration --data '{
 198    "application_type": "private",
 199    "redirect_uris":
 200      ["https://client.example.org/callback"],
 201    "post_logout_redirect_uris":
 202      ["https://client.example.org/logout/callback"],
 203    "client_name": "A Private App",
 204    "token_endpoint_auth_method": "client_secret_post",
 205    "contacts": ["me@example.org", "them@example.org"],
 206    "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"
 207   }'
 208 ```
 209
 210 Response:
 211 ```sh
 212 {
 213     "client_id": "LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA",
 214     "client_secret": "j21ecvLmFi9HPc_Hv0t7Ptmf1pVcZQLtHjIdU7U9tkS9WAjFJwVMav0G8ogTJ62q4BATovC7BQ19Qagc4x9BBg",
 215     "registration_access_token": "uiDSXx2GNSvYy5n8eW50aGrJz0HjaGpUdrGf07Agv_Q",
 216     "registration_client_uri": "https:\/\/localhost:9300\/oauth2\/default\/client\/6eUVG0-qK2dYiwfYdECKIw",
 217     "client_id_issued_at": 1604767861,
 218     "client_secret_expires_at": 0,
 219     "contacts": ["me@example.org", "them@example.org"],
 220     "application_type": "private",
 221     "client_name": "A Private App",
 222     "redirect_uris": ["https:\/\/client.example.org\/callback"],
 223     "token_endpoint_auth_method": "client_secret_post",
 224     "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"
 225 }
 226 ```
 227
 228 #### SMART on FHIR Registration
 229
 230 SMART Enabled Apps are supported.
 231
 232 SMART client can be registered at <website>/interface/smart/register-app.php. For example https://localhost:9300/interface/smart/register-app.php
 233
 234 After registering the SMART client, can then Enable it in OpenEMR at Administration->System->API Clients
 235
 236 After it is enabled, the SMART App will then be available to use in the Patient Summary screen (SMART Enabled Apps widget).
 237
 238 See this github issue for an example of a Smart App installation: https://github.com/openemr/openemr/issues/4148
 239
 240 ### Authorization Code Grant
 241
 242 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.
 243
 244 Note that a refresh token is only supplied if the `offline_access` scope is provided when requesting authorization grant.
 245
 246 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.
 247
 248 Example GET (this must be done in a browser):
 249 ```
 250 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
 251 ```
 252
 253 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.
 254
 255 Example Public Application POST
 256 ```
 257 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 258 'https://localhost:9300/oauth2/default/token'
 259 --data 'grant_type=authorization_code&client_id=yi4mnmVadpnqnJiOigkcGshuG-Kayiq6kmLqCJsYrk4redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback&code=def50...'
 260 ```
 261
 262 Example Private Application POST
 263 ```
 264 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded' \
 265     -H 'Authorization: Basic c3Z2TThFX1hISEhYUmtoZzUyeWoyNjdIOEYwQnpmT09pRmE4aUZBT290WTptbzZpZEFPaEU0UVYxb0lacUR5YTFHR1JHVGU5VDQzNWpzeTlRbWYxV2NiVFQ4NXhuZW5VdUpaUFR0bUZGT1QxVkhmYjZiclVvWWZ2Znd2NTFQejFldw==' \
 266     'https://localhost:9300/oauth2/default/token' \
 267     --data 'grant_type=authorization_code&client_id=yi4mnmVadpnqnJiOigkcGshuG-Kayiq6kmLqCJsYrk4redirect_uri=https%3A%2F%2Fclient.example.org%2Fcallback&code=def50...'
 268 ```
 269 ### Refresh Token Grant
 270
 271 Note that a refresh token is only supplied if the `offline_access` scope is provided when requesting authorization or password grant.
 272
 273 Example:
 274
 275 ```sh
 276 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 277 -i 'https://localhost:9300/oauth2/default/token'
 278 --data 'grant_type=refresh_token
 279 &client_id=LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA
 280 &refresh_token=def5020089a766d16...'
 281 ```
 282
 283 Response:
 284
 285 ```json
 286 {
 287   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYn...",
 288   "token_type": "Bearer",
 289   "expires_in": 3599,
 290   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYnl1RkRp...",
 291   "refresh_token": "def5020017b484b0add020bf3491a8a537fa04eda12..."
 292 }
 293 ```
 294
 295 ### Password Grant
 296
 297 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)'.
 298
 299 Note that all scopes are included in these examples for demonstration purposes. For production purposes, should only include the necessary scopes.
 300
 301 Note that a refresh token is only supplied if the `offline_access` scope is provided when requesting password grant.
 302
 303 Example for `users` role:
 304 ```sh
 305 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 306 -i 'https://localhost:9300/oauth2/default/token'
 307 --data 'grant_type=password
 308 &client_id=LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA
 309 &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
 310 &user_role=users
 311 &username=admin
 312 &password=pass'
 313 ```
 314
 315 Example for `patient` role:
 316 ```sh
 317 curl -X POST -k -H 'Content-Type: application/x-www-form-urlencoded'
 318 -i 'https://localhost:9300/oauth2/default/token'
 319 --data 'grant_type=password
 320 &client_id=LnjqojEEjFYe5j2Jp9m9UnmuxOnMg4VodEJj3yE8_OA
 321 &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
 322 &user_role=patient
 323 &username=Phil1
 324 &password=phil
 325 &email=heya@invalid.email.com'
 326 ```
 327
 328 Response:
 329
 330 ```json
 331 {
 332   "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYn...",
 333   "token_type": "Bearer",
 334   "expires_in": 3599,
 335   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJrYnl1RkRp...",
 336   "refresh_token": "def5020017b484b0add020bf3491a8a537fa04eda12..."
 337 }
 338 ```
 339
 340 ### Client Credentials Grant
 341
 342 This is an advanced grant that uses JSON Web Key Sets(JWKS) to authenticate and identify the client.  This credential grant is
 343 required to be used for access to any **system/\*.$export** scopes.  API clients must register either web accessible JWKS URI that hosts
 344 a RSA384 compatible key, or provide their JWKS as part of the registration. Client Credentials Grant access tokens are short
 345 lived and valid for only 1 minute and no refresh token is issued.  Tokens are requested at `/oauth2/default/token`
 346 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).
 347
 348 ### Logout
 349
 350 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.
 351
 352 ### More Details
 353
 354 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
 355
 356 More specific development api topics are discussed and described on the above forum thread (such as introspection).
 357
 358 ## Standard API Documentation
 359
 360 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`.
 361
 362 OpenEMR standard endpoints Use `https://localhost:9300/apis/default/api as base URI.`
 363
 364 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
 365
 366 _Example:_ `https://localhost:9300/apis/default/api/patient` returns a resource of all Patients.
 367
 368 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.
 369
 370 Request:
 371
 372 ```sh
 373 curl -X GET 'https://localhost:9300/apis/default/api/patient/1/medical_problem' \
 374   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
 375 ```
 376
 377 ## Patient Portal API Documentation
 378
 379 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`.
 380
 381 This is under development and is considered EXPERIMENTAL.
 382
 383 Enable the Patient Portal API service (/portal/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Patient Portal REST API (EXPERIMENTAL)"
 384
 385 OpenEMR patient portal endpoints Use `https://localhost:9300/apis/default/portal as base URI.`
 386
 387 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
 388
 389 _Example:_ `https://localhost:9300/apis/default/portal/patient` returns a resource of the patient.
 390
 391 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.
 392
 393 Request:
 394
 395 ```sh
 396 curl -X GET 'https://localhost:9300/apis/default/portal/patient' \
 397   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
 398 ```
 399
 400 ## For Developers
 401
 402 -   For business logic, make or use the services [here](src/Services)
 403 -   For controller logic, make or use the classes [here](src/RestControllers)
 404 -   For routing declarations, use the class [here](_rest_routes.inc.php).
 405
 406 REST API endpoints are defined in the [primary routes file](_rest_routes.inc.php). The routes file maps an external, addressable
 407 endpoint to the OpenEMR controller which handles the request, and also handles the JSON data conversions.
 408
 409 ```php
 410 "POST /api/patient" => function () {
 411     RestConfig::authorization_check("patients", "demo");
 412     $data = (array) (json_decode(file_get_contents("php://input")));
 413     $return = (new PatientRestController())->post($data);
 414     RestConfig::apiLog($return, $data);
 415     return $return;
 416 }
 417 ```
 418
 419 At a high level, the request processing flow consists of the following steps:
 420
 421 ```
 422 JSON Request -> Controller Component -> Validation -> Service Component -> Database
 423 ```
 424
 425 The logical response flow begins with the database result:
 426
 427 ```
 428 Database Result -> Service Component -> Controller Component -> RequestControllerHelper -> JSON Response
 429 ```
 430
 431 The [RequestControllerHelper class](./src/RestControllers/RestControllerHelper.php) evaluates the Service Component's
 432 result and maps it to a http response code and response payload. Existing APIs should be updated to utilize the
 433 `handleProcessingResult` method as it supports the [Validator](./src/Validators/BaseValidator.php) components.
 434
 435 The [PatientRestController](./src/RestControllers/PatientRestController.php) may be used as a reference to see how APIs are
 436 integrated with `RequestControllerHelper::handleProcessingResult` and the `Validator` components.
 437
 438 Finally, APIs which are integrated with the new `handleProcessingResult` method utilize a common response format.
 439
 440 ```json
 441 {
 442     "validationErrors": [],
 443     "internalErrors": [],
 444     "data": < data payload >
 445 }
 446 ```
 447
 448 -   `validationErrors` contain "client based" data validation errors
 449 -   `internalErrors` contain server related errors
 450 -   `data` is the response payload, represented as an object/`{}` for single results or an array/`[]` for multiple results