FHIR_README.md

   1 # OpenEMR FHIR API Documentation
   2
   3 ## Overview
   4
   5 Easy-to-use JSON-based REST API for OpenEMR FHIR. All code is done in classes and separate from the view to help with codebase modernization efforts. See standard OpenEMR API docs [here](API_README.md)
   6
   7 ## Implementation
   8
   9 FHIR endpoints are defined in the [primary routes file](_rest_routes.inc.php). The routes file maps an external, addressable
  10 endpoint to the OpenEMR FHIR controller which handles the request, and also handles the JSON data conversions.
  11
  12 ```php
  13 "POST /fhir/Patient" => function () {
  14     RestConfig::authorization_check("patients", "demo");
  15     $data = (array)(json_decode(file_get_contents("php://input"), true));
  16     return (new FhirPatientRestController())->post($data);
  17 }
  18 ```
  19
  20 At a high level, the request processing flow consists of the following steps:
  21
  22 ```
  23 JSON Request -> FHIR Controller Component -> FHIR Validation -> Parsing FHIR Resource -> Standard Service Component -> Validation -> Database
  24 ```
  25
  26 The logical response flow begins with the database result:
  27
  28 ```
  29 Database Result -> Service Component -> FHIR Service Component -> Parse OpenEMR Record -> FHIR Controller Component -> RequestControllerHelper -> JSON Response
  30 ```
  31
  32 ### Sections
  33
  34 -   [FHIR API Endpoints](FHIR_README.md#fhir-endpoints)
  35     -   [Capability Statement](FHIR_README.md#capability-statement)
  36     -   [Patient](FHIR_README.md#patient-resource)
  37     -   [Encounter](FHIR_README.md#encounter-resource)
  38     -   [Practitioner](FHIR_README.md#practitioner-resource)
  39     -   [PractitionerRole](FHIR_README.md#practitionerrole-resource)
  40     -   [Immunization](FHIR_README.md#immunization-resource)
  41     -   [AllergyIntolerance](FHIR_README.md#allergyintolerance-resource)
  42     -   [Organization](FHIR_README.md#organization-resource)
  43     -   [Observation](FHIR_README.md#observation-resource)
  44     -   [QuestionnaireResponse](FHIR_README.md#questionnaireresponse-resource)
  45     -   [Condition](FHIR_README.md#condition-resource)
  46     -   [Procedure](FHIR_README.md#procedure-resource)
  47     -   [MedicationRequest](FHIR_README.md#medicationrequest-resource)
  48     -   [Medication](FHIR_README.md#medication-resource)
  49     -   [Location](FHIR_README.md#location-resource)
  50     -   [CareTeam](FHIR_README.md#careTeam-resource)
  51     -   [Provenance](FHIR_README.md#Provenance-resources)
  52 -   [Patient Portal FHIR API Endpoints](FHIR_README.md#patient-portal-fhir-endpoints)
  53     -   [Patient](FHIR_README.md#patient-portal-patient-resource)
  54
  55 ### Prerequisite
  56
  57 Enable the Standard FHIR service (/fhir/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Standard FHIR REST API"
  58
  59 Enable the Patient Portal FHIR service (/portalfhir/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Patient Portal FHIR REST API"
  60
  61 ### Using FHIR API Internally
  62
  63 There are several ways to make API calls from an authorized session and maintain security:
  64
  65 -   See the script at tests/api/InternalApiTest.php for examples of internal API use cases.
  66
  67 ### Multisite Support
  68
  69 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`.
  70
  71 ### Authorization
  72
  73 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.
  74
  75 See [Authorization](API_README.md#authorization) for more details.
  76
  77 ### FHIR Endpoints
  78
  79 Standard FHIR endpoints Use `http://localhost:8300/apis/default/fhir as base URI.`
  80
  81 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
  82
  83 _Example:_ `http://localhost:8300/apis/default/fhir/Patient` returns a Patient's bundle resource, etc
  84
  85 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.
  86
  87 Request:
  88
  89 ```sh
  90 curl -X GET 'http://localhost:8300/apis/fhir/Patient' \
  91   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNnZ3eGJZYmFrOXlxUjF4U290Y1g4QVVDd3JOcG5yYXZEaFlqaHFjWXJXRGNDQUtFZmJONkh2cElTVkJiaWFobHBqOTBYZmlNRXpiY2FtU01pSHk1UzFlMmgxNmVqZEhcL1ZENlNtaVpTRFRLMmtsWDIyOFRKZzNhQmxMdUloZmNJM3FpMGFKZ003OXdtOGhYT3dpVkx5b3BFRXQ1TlNYNTE3UW5TZ0dsUVdQbG56WjVxOVYwc21tdDlSQ3RvcDV3TEkiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6ImZoaXIifQ=='
  92 ```
  93
  94 ---
  95
  96 ### Capability Statement
  97
  98 #### GET fhir/metadata
  99
 100 This will return the Capability Statement.
 101
 102 ```sh
 103 curl -X GET 'http://localhost:8300/apis/default/fhir/metadata'
 104 ```
 105
 106 ---
 107
 108 ### Patient Resource
 109
 110 #### GET fhir/Patient
 111
 112 Request:
 113
 114 ```sh
 115 curl -X GET 'http://localhost:8300/apis/default/fhir/Patient'
 116 ```
 117
 118 #### GET fhir/Patient[id]
 119
 120 Request:
 121
 122 ```sh
 123 curl -X GET 'http://localhost:8300/apis/default/fhir/Patient/90a8923c-0b1c-4d0a-9981-994b143381a7'
 124 ```
 125
 126 -   Supported Search Parameters
 127     -   address
 128     -   address-city
 129     -   address-postalcode
 130     -   address-state
 131     -   birthdate
 132     -   email
 133     -   family
 134     -   gender
 135     -   given
 136     -   name
 137     -   phone
 138     -   telecom
 139
 140 #### POST fhir/Patient
 141
 142 Request:
 143
 144 ```sh
 145 curl -X POST -H 'Content-Type: application/fhir+json' 'http://localhost:8300/apis/default/fhir/Patient' -d \
 146 '{
 147   "resourceType": "Patient",
 148   "identifier": [ { "system": "urn:oid:1.2.36.146.595.217.0.1", "value": "12345" } ],
 149   "name": [ {
 150       "family": "Chalmers",
 151       "given": [ "Peter", "James" ]
 152   } ],
 153   "gender": "male",
 154   "birthDate": "1974-12-25"
 155 }'
 156 ```
 157
 158 #### PUT fhir/Patient/[id]
 159
 160 Request:
 161
 162 ```sh
 163 curl -X PUT -H 'Content-Type: application/fhir+json' 'http://localhost:8300/apis/default/fhir/Patient/90a8923c-0b1c-4d0a-9981-994b143381a7' -d \
 164 '{
 165   "resourceType": "Patient",
 166   "id": "1",
 167   "identifier": [ { "system": "urn:oid:1.2.36.146.595.217.0.1", "value": "12345" } ],
 168   "name": [ {
 169       "family": "Chalmers",
 170       "given": [ "Peter", "James" ]
 171   } ],
 172   "gender": "male",
 173   "birthDate": "1974-01-13",
 174   "address": [ {
 175       "line": [ "534 Erewhon St" ],
 176       "city": "PleasantVille",
 177       "state": "Vic",
 178       "postalCode": "3999"
 179   } ]
 180 }'
 181 ```
 182
 183 #### PATCH fhir/Patient/[id]
 184
 185 Request:
 186
 187 ```sh
 188 curl -X PATCH -H 'Content-Type: application/fhir+json' 'http://localhost:8300/apis/default/fhir/Patient/90a8923c-0b1c-4d0a-9981-994b143381a7' -d \
 189 '[
 190  {
 191    "op": "replace",
 192    "path": "/address/0/postalCode",
 193    "value": "M5C 2X8"
 194  },
 195  {
 196    "op": "replace",
 197    "path": "/birthDate",
 198    "value": "1974-02-13"
 199  }
 200 ]'
 201 ```
 202
 203 ---
 204
 205 ### Encounter Resource
 206
 207 #### GET fhir/Encounter
 208
 209 Request:
 210
 211 ```sh
 212 curl -X GET 'http://localhost:8300/apis/default/fhir/Encounter'
 213 ```
 214
 215 #### GET fhir/Encounter[id]
 216
 217 Request:
 218
 219 ```sh
 220 curl -X GET 'http://localhost:8300/apis/default/fhir/Encounter/90c196f2-51cc-4655-8858-3a80aebff3ef'
 221 ```
 222
 223 -   Supported Search Parameters
 224     -   \_id
 225     -   patient
 226     -   date {gt|lt|ge|le}
 227
 228 ---
 229
 230 ### Practitioner Resource
 231
 232 #### GET fhir/Practitioner
 233
 234 Request:
 235
 236 ```sh
 237 curl -X GET 'http://localhost:8300/apis/default/fhir/Practitioner'
 238 ```
 239
 240 #### GET fhir/Practitioner[id]
 241
 242 Request:
 243
 244 ```sh
 245 curl -X GET 'http://localhost:8300/apis/default/fhir/Practitioner/90a8923c-0b1c-4d0a-9981-994b143381a7'
 246 ```
 247
 248 -   Supported Search Parameters
 249     -   address
 250     -   address-city
 251     -   address-postalcode
 252     -   address-state
 253     -   email
 254     -   active
 255     -   family
 256     -   given
 257     -   name
 258     -   phone
 259     -   telecom
 260
 261 #### POST fhir/Practitioner
 262
 263 Request:
 264
 265 ```sh
 266 curl -X POST -H 'Content-Type: application/fhir+json' 'http://localhost:8300/apis/default/fhir/Practitioner' -d \
 267 '{
 268   "resourceType": "Practitioner",
 269   "identifier": [ { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1122334499" } ],
 270   "name": [ {
 271       "use": "official",
 272       "family": "Chalmers",
 273       "given": [ "Peter", "James" ]
 274   } ]
 275 }'
 276 ```
 277
 278 #### PATCH fhir/Practitioner/[id]
 279
 280 Request:
 281
 282 ```sh
 283 curl -X PATCH -H 'Content-Type: application/fhir+json' 'http://localhost:8300/apis/default/fhir/Practitioner/90a8923c-0b1c-4d0a-9981-994b143381a7' -d \
 284 '{
 285   "resourceType": "Practitioner",
 286   "identifier": [ { "system": "http://hl7.org/fhir/sid/us-npi", "value": "1155667799" } ],
 287   "name": [ {
 288       "use": "official",
 289       "family": "Theil",
 290       "given": [ "Katy", "Wilson" ]
 291   } ],
 292   "address": [ {
 293       "line": [ "534 Erewhon St" ],
 294       "city": "PleasantVille",
 295       "state": "Vic",
 296       "postalCode": "3999"
 297   } ]
 298 }'
 299 ```
 300
 301 ---
 302
 303 ### PractitionerRole Resource
 304
 305 #### GET fhir/PractitionerRole
 306
 307 Request:
 308
 309 ```sh
 310 curl -X GET 'http://localhost:8300/apis/default/fhir/PractitionerRole'
 311 ```
 312
 313 #### GET fhir/PractitionerRole/[id]
 314
 315 Request:
 316
 317 ```sh
 318 curl -X GET 'http://localhost:8300/apis/default/fhir/PractitionerRole/90de091a-91e9-4bbe-9a81-75ed623f65bf'
 319 ```
 320
 321 -   Supported Search Parameters
 322     -   speciality
 323     -   practitioner
 324
 325 ---
 326
 327 ### Immunization Resource
 328
 329 #### GET fhir/Immunization
 330
 331 Request:
 332
 333 ```sh
 334 curl -X GET 'http://localhost:8300/apis/default/fhir/Immunization'
 335 ```
 336
 337 #### GET fhir/Immunization/[id]
 338
 339 Request:
 340
 341 ```sh
 342 curl -X GET 'http://localhost:8300/apis/default/fhir/Immunization/90feaaa2-4097-4437-966e-c425d1958dd6'
 343 ```
 344
 345 -   Supported Search Parameters
 346     -   patient
 347
 348 ---
 349
 350 ### AllergyIntolerance Resource
 351
 352 #### GET fhir/AllergyIntolerance
 353
 354 Request:
 355
 356 ```sh
 357 curl -X GET 'http://localhost:8300/apis/default/fhir/AllergyIntolerance'
 358 ```
 359
 360 #### GET fhir/AllergyIntolerance/[id]
 361
 362 Request:
 363
 364 ```sh
 365 curl -X GET 'http://localhost:8300/apis/default/fhir/AllergyIntolerance/90feaaa2-4097-4437-966e-c425d1958dd6'
 366 ```
 367
 368 ---
 369
 370 ### Organization Resource
 371
 372 #### GET /fhir/Organization
 373
 374 Request:
 375
 376 ```sh
 377 curl -X GET 'http://localhost:8300/apis/default/fhir/Organization'
 378 ```
 379
 380 #### GET /fhir/Organization/:id
 381
 382 Request:
 383
 384 ```sh
 385 curl -X GET 'http://localhost:8300/apis/default/fhir/Organization/1'
 386 ```
 387
 388 ---
 389
 390 ### Observation Resource
 391
 392 #### GET /fhir/Observation
 393
 394 Request:
 395
 396 ```sh
 397 curl -X GET 'http://localhost:8300/apis/default/fhir/Observation'
 398 ```
 399
 400 #### GET /fhir/Observation/:uuid
 401
 402 Request:
 403
 404 ```sh
 405 curl -X GET 'http://localhost:8300/apis/default/fhir/Observation/9150635b-0705-4a27-8820-df8b56cf07eb'
 406 ```
 407
 408 ---
 409
 410 ### QuestionnaireResponse Resource
 411
 412 #### POST /fhir/QuestionnaireResponse
 413
 414 Request:
 415
 416 ```sh
 417 curl -X POST -H 'Content-Type: application/fhir+json' 'http://localhost:8300/apis/default/fhir/QuestionnaireResponse' -d \
 418 '{
 419   "resourceType": "QuestionnaireResponse",
 420   "id": "697485",
 421   "meta": {
 422     "versionId": "1",
 423     "lastUpdated": "2020-03-22T09:11:45.181+00:00",
 424     "source": "#L0otRLyoImuOVD2S"
 425   },
 426   "status": "completed",
 427   "item": [ {
 428     "linkId": "1",
 429     "text": "Do you have allergies?"
 430   }, {
 431     "linkId": "2",
 432     "text": "General questions",
 433     "item": [ {
 434       "linkId": "2.1",
 435       "text": "What is your gender?"
 436     }, {
 437       "linkId": "2.2",
 438       "text": "What is your date of birth?"
 439     }]
 440   }]
 441   } ]
 442 }'
 443 ```
 444
 445 ---
 446
 447 ### Condition Resource
 448
 449 #### GET fhir/Condition
 450
 451 Request:
 452
 453 ```sh
 454 curl -X GET 'http://localhost:8300/apis/default/fhir/Condition'
 455 ```
 456
 457 #### GET fhir/Condition/[id]
 458
 459 Request:
 460
 461 ```sh
 462 curl -X GET 'http://localhost:8300/apis/default/fhir/Condition/9109890a-6756-44c1-a82d-bdfac91c7424'
 463 ```
 464
 465 ---
 466
 467 ### Procedure Resource
 468
 469 #### GET /fhir/Procedure
 470
 471 Request:
 472
 473 ```sh
 474 curl -X GET 'http://localhost:8300/apis/default/fhir/Procedure'
 475 ```
 476
 477 #### GET /fhir/Procedure/:uuid
 478
 479 Request:
 480
 481 ```sh
 482 curl -X GET 'http://localhost:8300/apis/default/fhir/Procedure/9109890a-6756-44c1-a82d-bdfac91c7424'
 483 ```
 484
 485 ---
 486
 487 ### MedicationRequest Resource
 488
 489 #### GET /fhir/MedicationRequest
 490
 491 Request:
 492
 493 ```sh
 494 curl -X GET 'http://localhost:8300/apis/default/fhir/MedicationRequest'
 495 ```
 496
 497 #### GET /fhir/MedicationRequest/:uuid
 498
 499 Request:
 500
 501 ```sh
 502 curl -X GET 'http://localhost:8300/apis/default/fhir/MedicationRequest/9128a1ec-95be-4649-8a66-d3686b7ab0ca'
 503 ```
 504
 505 ---
 506
 507 ### Medication Resource
 508
 509 #### GET /fhir/Medication
 510
 511 Request:
 512
 513 ```sh
 514 curl -X GET 'http://localhost:8300/apis/default/fhir/Medication'
 515 ```
 516
 517 #### GET /fhir/Medication/:uuid
 518
 519 Request:
 520
 521 ```sh
 522 curl -X GET 'http://localhost:8300/apis/default/fhir/Medication/9109890a-6756-44c1-a82d-bdfac91c7424'
 523 ```
 524
 525 ---
 526
 527 ### Location Resource
 528
 529 #### GET /fhir/Location
 530
 531 Request:
 532
 533 ```sh
 534 curl -X GET 'http://localhost:8300/apis/default/fhir/Location'
 535 ```
 536
 537 #### GET /fhir/Location/:uuid
 538
 539 Request:
 540
 541 ```sh
 542 curl -X GET 'http://localhost:8300/apis/default/fhir/Location/90f3d0e9-2a19-453b-84bd-1fa2b533f96c'
 543 ```
 544
 545 ---
 546
 547 ### CareTeam Resource
 548
 549 #### GET /fhir/CareTeam
 550
 551 Request:
 552
 553 ```sh
 554 curl -X GET 'http://localhost:8300/apis/default/fhir/CareTeam'
 555 ```
 556
 557 #### GET /fhir/CareTeam/:uuid
 558
 559 Request:
 560
 561 ```sh
 562 curl -X GET 'http://localhost:8300/apis/default/fhir/CareTeam/915e8fb4-86b2-4365-a420-d46fc07d5aed'
 563 ```
 564
 565 ---
 566
 567 ### Provenance Resources
 568
 569 Provenance resources are requested by including `_revinclude=Provenance:target` in the search of a resource. Is currently supported for the following resources:
 570   - AllergyIntolerance
 571       ```sh
 572       curl -X GET 'http://localhost:8300/apis/default/fhir/AllergyIntolerance?_revinclude=Provenance:target'
 573       ```
 574
 575 ## Patient Portal FHIR Endpoints
 576
 577 OpenEMR patient portal fhir endpoints Use `http://localhost:8300/apis/default/portalfhir as base URI.`
 578
 579 Note that the `default` component can be changed to the name of the site when using OpenEMR's multisite feature.
 580
 581 _Example:_ `http://localhost:8300/apis/default/portalfhir/Patient` returns a resource of the patient.
 582
 583 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.
 584
 585 Request:
 586
 587 ```sh
 588 curl -X GET 'http://localhost:8300/apis/default/portalfhir/Patient' \
 589   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
 590 ```
 591
 592 ---
 593
 594 ### Patient Portal Patient Resource
 595
 596 #### GET /portalfhir/Patient
 597
 598 Request:
 599
 600 ```sh
 601 curl -X GET 'http://localhost:8300/apis/default/portalfhir/Patient'
 602 ```