Merge pull request #2003 from sjpadgett/bug-fix
[openemr.git] / API_README.md
blobd1dd51245c8f19792aef5b298b7869be2db835e0
1 ![img](./public/images/openemr-rest-api.png)
3 ### Goal
5 This project aims to provide an easy-to-use JSON-based REST API for OpenEMR's most common functions. All code will be done in classes and separate from the view to help with codebase modernization efforts.
7 ### Team
9 - [@matthewvita](https://github.com/matthewvita)
10 - [@sjpadgett](https://github.com/sjpadgett)
11 - [@juggernautsei](https://github.com/juggernautsei)
12 - [@kofiav](https://github.com/kofiav)
13 - [@bradymiller](https://github.com/bradymiller)
15 ### Prerequsite
16 Enable this API service in OpenEMR menu: Administration->Globals Connectors tab.
18 ### Endpoints
19 Note: FHIR endpoints follow normal FHIR REST endpoints. Use `https://domain/apis/fhir as base URL.`
21 _Example:_ `https://domain/apis/fhir/Patient` returns a Patients bundle resource and etc..
23 #### POST /api/auth
25 Obtain an API token with your login (returns an API token). For FHIR replace Uri component 'api' with 'fhir':
27 ```
28 curl -X POST 'https://localhost:8300/apis/api/auth' \
29 -d '{
30     "grant_type":"password",
31     "username": "ServiceUser",
32     "password": "password",
33     "client_id":"site id"
35 ```
36 Response:
37 ```
39 "token_type":"Bearer",
40 "access_token":"d2870cb522230dbb8946b2f47d2c7e6664656661756c74",
41 "expires_in":"3600"
43 ```
44 Each call must include the token:
46 ```
47 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem' \
48   -H 'Authorization: Bearer d2870cb522230dbb8946b2f47d2c7e6664656661756c74'
49 ```
51 #### POST /api/facility
53 ```
54 curl -X POST 'http://localhost:8300/apis/api/facility' -d \
56     "name": "Aquaria",
57     "phone": "808-606-3030",
58     "fax": "808-606-3031",
59     "street": "1337 Bit Shifter Ln",
60     "city": "San Lorenzo",
61     "state": "ZZ",
62     "postal_code": "54321",
63     "email": "foo@bar.com",
64     "service_location": "1",
65     "billing_location": "1",
66     "color": "#FF69B4"
68 ```
70 #### PUT /api/facility/:fid
72 ```
73 curl -X PUT 'http://localhost:8300/apis/api/facility/1' -d \
75     "name": "Aquaria",
76     "phone": "808-606-3030",
77     "fax": "808-606-3031",
78     "street": "1337 Bit Shifter Ln",
79     "city": "San Lorenzo",
80     "state": "AZ",
81     "postal_code": "54321",
82     "email": "foo@bar.com",
83     "service_location": "1",
84     "billing_location": "1",
85     "color": "#FF69B4"
87 ```
89 #### GET /api/facility
91 ```
92 curl -X GET 'http://localhost:8300/apis/api/facility'
93 ```
95 #### GET /api/facility/:fid
97 ```
98 curl -X GET 'http://localhost:8300/apis/api/facility/1'
99 ```
101 #### GET /api/provider
104 curl -X GET 'http://localhost:8300/apis/api/provider'
107 #### GET /api/provider/:prid
110 curl -X GET 'http://localhost:8300/apis/api/provider/1'
113 #### POST /api/patient
116 curl -X POST 'http://localhost:8300/apis/api/patient' -d \
118     "title": "Mr",
119     "fname": "Foo",
120     "mname": "",
121     "lname": "Bar",
122     "street": "456 Tree Lane",
123     "postal_code": "08642",
124     "city": "FooTown",
125     "state": "FL",
126     "country_code": "US",
127     "phone_contact": "123-456-7890",
128     "dob": "1992-02-02",
129     "sex": "Male",
130     "race": "",
131     "ethnicity": ""
135 #### PUT /api/patient/:pid
138 curl -X PUT 'http://localhost:8300/apis/api/patient/1' -d \
140     "title": "Mr",
141     "fname": "Baz",
142     "mname": "",
143     "lname": "Bop",
144     "street": "456 Tree Lane",
145     "postal_code": "08642",
146     "city": "FooTown",
147     "state": "FL",
148     "country_code": "US",
149     "phone_contact": "123-456-7890",
150     "dob": "1992-02-03",
151     "sex": "Male",
152     "race": "",
153     "ethnicity": ""
157 #### GET /api/patient
160 curl -X GET 'http://localhost:8300/apis/api/patient'
164 curl -X GET 'http://localhost:8300/apis/api/patient&fname=...&lname=...&dob=...'
167 #### GET /api/patient/:pid
170 curl -X GET 'http://localhost:8300/apis/api/patient/1'
173 #### GET /api/patient/:pid/encounter
176 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter'
179 #### GET /api/patient/:pid/encounter/:eid
182 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1'
185 #### POST /api/patient/:pid/encounter/:eid/vital
188 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/vital' -d \
190     "bps": "130",
191     "bpd": "80",
192     "weight": "220",
193     "height": "70",
194     "temperature": "98",
195     "temp_method": "Oral",
196     "pulse": "60",
197     "respiration": "20",
198     "note": "...",
199     "waist_circ": "37",
200     "head_circ": "22.2",
201     "oxygen_saturation": "80"
205 #### PUT /api/patient/:pid/encounter/:eid/vital/:vid
208 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1' -d \
210     "bps": "140",
211     "bpd": "80",
212     "weight": "220",
213     "height": "70",
214     "temperature": "98",
215     "temp_method": "Oral",
216     "pulse": "60",
217     "respiration": "20",
218     "note": "...",
219     "waist_circ": "37",
220     "head_circ": "22.2",
221     "oxygen_saturation": "80"
225 #### GET /api/patient/:pid/encounter/:eid/vital
228 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital'
231 #### GET /api/patient/:pid/encounter/:eid/vital/:vid
234 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1'
237 #### POST /api/patient/:pid/encounter/:eid/soap_note
240 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note' -d \
242     "subjective": "...",
243     "objective": "...",
244     "assessment": "...",
245     "plan": "..."
249 #### PUT /api/patient/:pid/encounter/:eid/soap_note/:sid
252 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1' -d \
254     "subjective": "...",
255     "objective": "...",
256     "assessment": "...",
257     "plan": "..."
261 #### GET /api/patient/:pid/encounter/:eid/soap_note
264 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note'
267 #### GET /api/patient/:pid/encounter/:eid/soap_note/:sid
270 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1'
273 #### POST /api/patient/:pid/medical_problem
276 curl -X POST 'http://localhost:8300/apis/api/patient/1/medical_problem' -d \
278     "title": "Dermatochalasis",
279     "begdate": "2010-04-13",
280     "enddate": null,
281     "diagnosis": "ICD10:H02.839"
285 #### PUT /api/patient/:pid/medical_problem/:mid
288 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medical_problem/1' -d \
290     "title": "Dermatochalasis",
291     "begdate": "2010-04-13",
292     "enddate": "2018-03-12",
293     "diagnosis": "ICD10:H02.839"
297 #### GET /api/patient/:pid/medical_problem
300 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem'
303 #### GET /api/patient/:pid/medical_problem/:mid
306 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
309 #### DELETE /api/patient/:pid/medical_problem/:mid
312 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
315 #### POST /api/patient/:pid/allergy
318 curl -X POST 'http://localhost:8300/apis/api/patient/1/allergy' -d \
320     "title": "Iodine",
321     "begdate": "2010-10-13",
322     "enddate": null
326 #### PUT /api/patient/:pid/allergy/:aid
329 curl -X PUT 'http://localhost:8300/apis/api/patient/1/allergy/1' -d \
331     "title": "Iodine",
332     "begdate": "2012-10-13",
333     "enddate": null
337 #### GET /api/patient/:pid/allergy
340 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy'
343 #### GET /api/patient/:pid/allergy/:aid
346 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy/1'
349 #### DELETE /api/patient/:pid/allergy/:aid
352 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/allergy/1'
355 #### POST /api/patient/:pid/medication
358 curl -X POST 'http://localhost:8300/apis/api/patient/1/medication' -d \
360     "title": "Norvasc",
361     "begdate": "2013-10-13",
362     "enddate": null
366 #### PUT /api/patient/:pid/medication/:mid
369 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medication/1' -d \
371     "title": "Norvasc",
372     "begdate": "2013-04-13",
373     "enddate": null
377 #### GET /api/patient/:pid/medication
380 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication'
383 #### GET /api/patient/:pid/medication/:mid
386 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication/1'
389 #### DELETE /api/patient/:pid/medication/:mid
392 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medication/1'
395 #### POST /api/patient/:pid/surgery
398 curl -X POST 'http://localhost:8300/apis/api/patient/1/surgery' -d \
400     "title": "Blepharoplasty",
401     "begdate": "2013-10-13",
402     "enddate": null,
403     "diagnosis": "CPT4:15823-50"
407 #### PUT /api/patient/:pid/surgery/:sid
410 curl -X PUT 'http://localhost:8300/apis/api/patient/1/surgery/1' -d \
412     "title": "Blepharoplasty",
413     "begdate": "2013-10-14",
414     "enddate": null,
415     "diagnosis": "CPT4:15823-50"
419 #### GET /api/patient/:pid/surgery
422 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery'
425 #### GET /api/patient/:pid/surgery/:sid
428 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery/1'
431 #### DELETE /api/patient/:pid/surgery/:sid
434 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/surgery/1'
437 #### POST /api/patient/:pid/dental_issue
440 curl -X POST 'http://localhost:8300/apis/api/patient/1/dental_issue' -d \
442     "title": "Halitosis",
443     "begdate": "2015-03-17",
444     "enddate": null
448 #### PUT /api/patient/:pid/dental_issue/:did
451 curl -X PUT 'http://localhost:8300/apis/api/patient/1/dental_issue/1' -d \
453     "title": "Halitosis",
454     "begdate": "2015-03-17",
455     "enddate": "2018-03-20"
459 #### GET /api/patient/:pid/dental_issue
462 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue'
465 #### GET /api/patient/:pid/dental_issue/:did
468 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
471 #### DELETE /api/patient/:pid/dental_issue/:did
474 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
477 #### GET /api/patient/:pid/insurance
480 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance'
483 #### GET /api/patient/:pid/insurance/:type
486 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance/secondary'
489 #### POST /api/patient/:pid/insurance/:type
492 curl -X POST 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
494     "type": "primary",
495     "provider": "33",
496     "plan_name": "Some Plan",
497     "policy_number": "12345",
498     "group_number": "252412",
499     "subscriber_lname": "Tester",
500     "subscriber_mname": "Xi",
501     "subscriber_fname": "Foo",
502     "subscriber_relationship": "other",
503     "subscriber_ss": "234231234",
504     "subscriber_DOB": "2018-10-03",
505     "subscriber_street": "183 Cool St",
506     "subscriber_postal_code": "23418",
507     "subscriber_city": "Cooltown",
508     "subscriber_state": "AZ",
509     "subscriber_country": "USA",
510     "subscriber_phone": "234-598-2123",
511     "subscriber_employer": "Some Employer",
512     "subscriber_employer_street": "123 Heather Lane",
513     "subscriber_employer_postal_code": "23415",
514     "subscriber_employer_state": "AZ",
515     "subscriber_employer_country": "USA",
516     "subscriber_employer_city": "Cooltown",
517     "copay": "35",
518     "date": "2018-10-15",
519     "subscriber_sex": "Female",
520     "accept_assignment": "TRUE",
521     "policy_type": "a"
525 Notes:
526 - `provider` is the insurance company id
527 - `state` can be found by querying `resource=/api/list/state`
528 - `country` can be found by querying `resource=/api/list/country`
531 #### PUT /api/patient/:pid/insurance/:type
534 curl -X PUT 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
536     "type": "primary",
537     "provider": "33",
538     "plan_name": "Some Plan",
539     "policy_number": "12345",
540     "group_number": "252412",
541     "subscriber_lname": "Tester",
542     "subscriber_mname": "Xi",
543     "subscriber_fname": "Foo",
544     "subscriber_relationship": "other",
545     "subscriber_ss": "234231234",
546     "subscriber_DOB": "2018-10-03",
547     "subscriber_street": "183 Cool St",
548     "subscriber_postal_code": "23418",
549     "subscriber_city": "Cooltown",
550     "subscriber_state": "AZ",
551     "subscriber_country": "USA",
552     "subscriber_phone": "234-598-2123",
553     "subscriber_employer": "Some Employer",
554     "subscriber_employer_street": "123 Heather Lane",
555     "subscriber_employer_postal_code": "23415",
556     "subscriber_employer_state": "AZ",
557     "subscriber_employer_country": "USA",
558     "subscriber_employer_city": "Cooltown",
559     "copay": "35",
560     "date": "2018-10-15",
561     "subscriber_sex": "Female",
562     "accept_assignment": "TRUE",
563     "policy_type": "a"
567 Notes:
568 - `provider` is the insurance company id
569 - `state` can be found by querying `resource=/api/list/state`
570 - `country` can be found by querying `resource=/api/list/country`
572 #### GET /api/list/:list_name
575 curl -X GET 'http://localhost:8300/apis/api/list/medical_problem_issue_list'
578 #### GET /api/version
581 curl -X GET 'http://localhost:8300/apis/api/version'
584 #### GET /api/product
587 curl -X GET 'http://localhost:8300/apis/api/product'
590 #### GET /api/insurance_company
593 curl -X GET 'http://localhost:8300/apis/api/insurance_company'
596 #### GET /api/insurance_type
599 curl -X GET 'http://localhost:8300/apis/api/insurance_type'
602 #### POST /api/insurance_company
605 curl -X POST 'http://localhost:8300/apis/api/insurance_company' -d \
607     "name": "Cool Insurance Company",
608     "attn": null,
609     "cms_id": null,
610     "ins_type_code": "2",
611     "x12_receiver_id": null,
612     "x12_default_partner_id": null,
613     "alt_cms_id": "",
614     "line1": "123 Cool Lane",
615     "line2": "Suite 123",
616     "city": "Cooltown",
617     "state": "CA",
618     "zip": "12245",
619     "country": "USA"
623 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
625 #### PUT /api/insurance_company/:iid
628 curl -X PUT 'http://localhost:8300/apis/api/insurance_company/1' -d \
630     "name": "Super Insurance Company",
631     "attn": null,
632     "cms_id": null,
633     "ins_type_code": "2",
634     "x12_receiver_id": null,
635     "x12_default_partner_id": null,
636     "alt_cms_id": "",
637     "line1": "123 Cool Lane",
638     "line2": "Suite 123",
639     "city": "Cooltown",
640     "state": "CA",
641     "zip": "12245",
642     "country": "USA"
646 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
648 #### GET /api/appointment
651 curl -X GET 'http://localhost:8300/apis/api/appointment'
654 #### GET /api/appointment/:eid
657 curl -X GET 'http://localhost:8300/apis/api/appointment/1'
660 #### GET /api/patient/:pid/appointment
663 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment'
666 #### GET /api/patient/:pid/appointment/:eid
669 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment/1'
672 #### POST /api/patient/:pid/appointment
675 curl -X POST 'http://localhost:8300/apis/api/patient/1/appointment' -d \
677     "pc_eid":"1",
678     "pc_catid": "5",
679     "pc_title": "Office Visit",
680     "pc_duration": "900",
681     "pc_hometext": "Test",
682     "pc_apptstatus": "-",
683     "pc_eventDate": "2018-10-19",
684     "pc_startTime": "09:00",
685     "pc_facility": "9",
686     "pc_billing_location": "10"
690 #### DELETE /api/patient/:pid/appointment/:eid
693 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/appointment/1' -d \
696 #### GET /api/patient/:pid/document
699 curl -X GET 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye'
702 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
704 - Spaces are represented with `_`
705 - All characters are lowercase
707 #### POST /api/patient/:pid/document
710 curl -X POST 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye' \
711  -F document=@/home/someone/Desktop/drawing.jpg
714 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
716 - Spaces are represented with `_`
717 - All characters are lowercase
719 #### GET /api/patient/:pid/document/:did
722 wget 'http://localhost:8300/apis/api/patient/1/document/1'
725 #### POST /api/patient/:pid/message
728 curl -X POST 'http://localhost:8300/apis/api/patient/1/message' -d \
730     "body": "Test 123",
731     "groupname": "Default",
732     "from": "admin",
733     "to": "Matthew",
734     "title": "Other",
735     "message_status": "New"
739 Notes:
740 - For `title`, use `resource=/api/list/note_type`
741 - For `message_type`, use `resource=/api/list/message_status`
743 #### PUT /api/patient/:pid/message/:mid
746 curl -X PUT 'http://localhost:8300/apis/api/patient/1/message/1' -d \
748     "body": "Test 456",
749     "groupname": "Default",
750     "from": "Matthew",
751     "to": "admin",
752     "title": "Other",
753     "message_status": "New"
757 Notes:
758 - For `title`, use `resource=/api/list/note_type`
759 - For `message_type`, use `resource=/api/list/message_status`
761 #### DELETE /api/patient/:pid/message/:mid
764 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/message/1'
767 ### Dev Notes
769 - For business logic, make or use the services [here](https://github.com/openemr/openemr/tree/master/services)
770 - For controller logic, make or use the classes [here](https://github.com/openemr/openemr/tree/master/rest_controllers)
771 - For routing declarations, use the class [here](https://github.com/openemr/openemr/blob/master/_rest_routes.inc.php).
774 ### Project Management
776 - TODO(team): Consider using Symfony's router
777 - TODO(sherwin): Encounter POST
778 - TODO(matthew): Fix authorization piece
779 - TODO(?): Support CouchDB with document API
780 - TODO(?): Prevent `ListService` from using `enddate` of `0000-00-00` by default
781 - TODO(?): API for fee sheets
782 - TODO(?): API for pharmacies
783 - TODO(?): API for immunizations
784 - TODO(?): API for prescriptions
785 - TODO(?): Drug search API
786 - TODO(?): API for onotes
789 ### What is that dog drawing?
791 That is Peppy, an old OpenEMR mascot. Long live Peppy!
794 ### License
796 [GNU GPL](../LICENSE)