This is the technical API documentation (focusing on client devs) for the REST API.

- 1.1 Resources
- 1.2 URI Conventions
- 1.3 Sample REST calls
  - 1.3.1 Authenticate and get a session ID
  - 1.3.2 Authentication
  - 1.3.3 Create Person
- 1.4 Response Format
2 Configuration of REST Call

Resources

Every available object in the web services 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).

URI Conventions

Because there are so many options when creating REST URLs, we have laid out a set of conventions that all REST developers should follow. This will keep our web service API looking neat and uniform across all different types of objects and modules.

For resource,
- GET /ws/rest/v1/resource?q=query = search
- GET /ws/rest/v1/resource/uuid = retrieve
- POST /ws/rest/v1/resource = create
  - Request body contains data to persist (not in request params)
- POST /ws/rest/v1/resource/uuid = partial update of the resource
  - Request body contains just the fields to update (not in request params)
DELETE /ws/rest/v1/resource/uuid = void for data, retire for metadata
DELETE /ws/rest/v1/resource/uuid?purge=true = purge (aka delete from the database entirely)
Do not put verbs in the URL; represent them with sub-resources.
- For example, instead of addNameToPerson, we POST to /ws/rest/person/uuid/names
URLs:
- Are prefixed with /ws/rest/ due to servlet forwarding in OpenMRS, followed by an API version number (currently /v1)
- The URL should be written in all-lowercase ASCII letters
- No special characters (e.g. no spaces or underscores)
- Hyphens are ok if absolutely necessary
- No extensions allowed (acceptHeader will be used to specify json or xml content. All json for release 1.0)
Subresources should have their URIs inside the URI of their parent (like /ws/rest/person/uuid/name/nameuuid)
Domain objects that are separately managed get their own URI. (e.g. /ws/rest/v1/enrollment/uuid instead of /ws/rest/v1/program/uuid/enrollments/uuid)
Hide (don't expose) "helper" classes as much as possible (e.g. web service clients should never see ConceptSet, etc)
Resource names should usually be the same as the domain objects they represent, but they may differ if the domain object name is confusing.
- For example org.openmrs.PatientProgram is /ws/rest/v1/enrollment

E.g: When saving or editing a property on a "Concept" object, the conceptDatatype property can be simply the uuid. In addition, for most metadata, the "name" is unique across all active metadata, so that can also be used in place of the uuid when saving as well (POST or PUT).

To see all the resources visit - https://intelehealthwiki.atlassian.net/wiki/spaces/INTELEHEAL/pages/328754

Sample REST calls

Authenticate and get a session ID

This is useful to verify connectivity and credentials.

/ws/rest/v1/session

Authentication

Nearly every method (other than the /session endpoint) in the OpenMRS API requires authentication; therefore, every method in the webservices module needs to have an authenticated user in order to work.
There is a filter defined on the module that intercepts all calls and authenticates the given request.
Currently, only BASIC authentication is supported. Along with the HTTP request, a request header of Authorization: Basic (base64 of username: password) needs to be sent.
Alternatively, a session token can be used. GET /openmrs/ws/rest/v1/session with the BASIC credentials will return the current token value. This token should be passed with all subsequent calls as a cookie named jsessionid=token.
A DELETE call on the /openmrs/ws/rest/v1/session will logout the user and end the session.

Create Person

To create a person call post request to URL

/ws/rest/v1/person

body resources:

{
  "birthdateEstimated": "string",
  "deathdateEstimated": "string",
  "addresses": "string",
  "names": "string",
  "birthdate": "string",
  "gender": "string",
  "deathDate": "string",
  "dead": "string",
  "attributes": "string",
  "birthtime": "string",
  "causeOfDeath": "string",
  "age": "string"
}

To see all the Rest Call visit - API Documentation

Response Format

OpenMRS allows us to offer both json and xml formats for every object. If you want to receive a json response, be sure to insert a header of "Accept: application/json". If xml is your thing, use "Accept: application/xml".

When POSTing content, use the "Content-Type" header to specify the data format you are sending to the server.

Configuration of REST Call

How to Limit the number of results and paging?

When you do a GET request that returns a very large number of results (either by getting all instances or doing a search), the number of results returned is limited.

Clients may request more or fewer results with the limit parameter. For example:

How to format 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)

How to get the location without authentication?

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

How to change your password?

After authenticating you can change your own password, by POST .../openmrs/ws/rest/v1/password with oldPassword and newPassword in the request body.
An administrator (with the EDIT_USER_PASSWORDS privilege) can change the password for other users by POST .../openmrs/ws/rest/v1/password/<uuidOfOtherUser> with newPassword in the request body.

Intelehealth

Rest Web Service