This is the technical API documentation (focusing on client devs) for the REST Module. For general REST web service information and user documentation, see that the module page.
| Table of Contents |
|---|
Resources
Every available object in the web services (ws) module is written up as a resource. The resource class defines the properties that are exposed and the setters that are available. The class also defines the representations and what goes in them (ref vs default vs full, see below for more on representations).
...
There are some objects that are not defined or do not make sense apart from their parent object. These we refer to as subresources. Examples are PersonNames, PersonAddresses, ConceptNames, etc. You can act on subresources under the parent url:.
Examples:
| Code Block | ||
|---|---|---|
| ||
POST /openmrs/ws/rest/v1/person/uuidofperson:target_person_uuid/name Body content: {{ "givenName": "John", "familyName": "Smith"} | ||
| Code Block | ||
| ||
POST /ws/rest/v1/person/uuidofperson/name/uuidofname Body content: {"givenName": "Johnny"} |
A subresource can have only one parent. If it seems like an object has two or more parents, then it is most likely a top-level resource. E.g. "encounters" should not be a subresource of "patient" + and "location" (answering questions of both "all encounters of a patient" and "all encounters at a location"). Instead, these should be queries on the encounter resource: /ws/rest/v1/encounter?patient=349234-2349234 and /ws/rest/v1/encounter?location=3423482-34923-23
...
Some resources can have multiple subtypes, for example the order resource contains drugorder and testorder subtypes. When creating a resource that has subtypes via a POST, you must specify which subtype of the resource you are creating, with a special t property of the object. For example:
| Code Block |
|---|
POST /openmrs/ws/rest/v1/order
Body content:
{"t": "testorder", /*... and other properties */} |
...
If you are looking for some sample REST calls, please see Sample REST calls. You can also explore controller tests to see which requests are possible: https://github.com/openmrs/openmrs-module-webservices.rest/search?q=Controller+test&type=Code
...
Both the REST and Java API follow the same default behaviour except for the case of getting metadata from the Java API, see the summary table below:
| REST API | Java API |
|---|---|
|
|
|
|
Date/Time with Time Zones
It is strongly recommended to always submit the full date + time + timezone in any REST POST query.
The format of the date/time should be:
“2016-12-25T19:02:34.232+0700”
(the milliseconds are optional)
e.g.
| Code Block | ||
|---|---|---|
| ||
POST /ws/rest/v1/obs
Body content:
{"obsDatetime": "2016-12-25T19:02:34.232+0700", /*... and other properties */} |
...
Fetching locations requires you to authenticate the user first. If it is a required to display all locations prior to login or without authentication you can do it by using GET .../openmrs/ws/rest/v1/location?tag=Login%LocationLogin%20Location
Changing your password
Since version 2.17 of the webservices.rest module:
...