Page Comparison

What this module does

The module exposes the OpenMRS API as REST web services.  if If an OpenMRS instance is running the Webservices.REST module, other programs (and languages) can connect to retrieve and post certain information through to an OpenMRS database.

User Documentation

The module exposes the OpenMRS API through light-weight resource objects of the core OpenMRS objects.

See REST Web Services User Guide for more information.Enhanced Web Services (Design Page)

Technical Documentation

This module uses Spring 3 annotations to expose URLs.  Primary transport language is currently JSON.

See REST Web Services API for documentation, API, conventions, and descriptions.

Full example of adding new web services to the core/trunk openmrs.

Full example of adding new web service methods into your module.

Technical Documentation for Implementing Clients

Using ETag (available with OpenMRS v1.9.0 revision 20638 and higher)
The module also adds an ETag to response headers when presenting resources to clients. ETags have been implemented in shallow-mode (i.e. they save client bandwidth, but not server-side processing). As described here, as a client application you may want to look at ETag when making REST calls.

From the wikipedia article:

In typical usage, when a URL is retrieved the web server will return the resource along with its corresponding ETag value, which is placed in an HTTP "ETag" field:

Code Block
ETag: "686897696a7c876b7e"

The client may then decide to cache the resource, along with its ETag. Later, if the client wants to retrieve the same URL again, it will send its previously saved copy of the ETag along with the request in a "If-None-Match" field.

Code Block
If-None-Match: "686897696a7c876b7e"

On this subsequent request, the server may now compare the client's ETag with the ETag for the current version of the resource. If the ETag values match, meaning that the resource has not changed, then the server may send back a very short response with an HTTP 304 Not Modified status. The 304 status tells the client that its cached version is still good and that it should use that.
However, if the ETag values do not match, meaning the resource has likely changed, then a full response including the resource's content is returned, just as if ETags were not being used. In this case the client may decide to replace its previously cached version with the newly returned resource and the new ETag.

Example using curl:

$ curl -i -u admin:test http://127.0.0.1:8080/openmrs/ws/rest/patient?q=Dar

RESPONSE HEADER IS:

HTTP/1.1 200 OK
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONID=1jw2itu9oyt5v;Path=/openmrs
Content-Type: application/json;charset=UTF-8
*ETag: "078c5b8fe25b332a40b4174bd38f5ee90"*
Content-Length: 399
Server: Jetty(6.1.10)

$ curl -i -u admin:test http://127.0.0.1:8080/openmrs/ws/rest/patient?q=Darius

RESPONSE HEADER IS:

HTTP/1.1 200 OK
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONID=1jw2itu9oyt5v;Path=/openmrs
Content-Type: application/json;charset=UTF-8
*ETag: "078c5b8fe25b332a40b4174bd38f5ee90"*
Content-Length: 399
Server: Jetty(6.1.10)

We see that both the ETag are same and hence the client knows that the response would be the same and can save bandwidth.

After some days, if Darius's records have not been updated then, the client can send the ETag and check for modifications:

$ curl -i -H 'If-None-Match:"078c5b8fe25b332a40b4174bd38f5ee90"' -u admin:test http://127.0.0.1:8080/openmrs/ws/rest/patient?q=Darius

RESPONSE IS:

HTTP/1.1 304 Not Modified
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Set-Cookie: JSESSIONID=dlcztsmushgm;Path=/openmrs
Content-Type: application/json;charset=UTF-8
ETag: "078c5b8fe25b332a40b4174bd38f5ee90"
Content-Length: 0
Server: Jetty(6.1.10)

From the 304 Not Modified, we know that the records are the same and the client doesn't have to get the data again.

Downloads

View Source: http://source.openmrs.org/browse/Modules/webservices.rest/trunk/
Checkout Source: http://svn.openmrs.org/openmrs-modules/webservices.rest/trunk/
Download: http://modules.openmrs.org/modules/view.jsp?module= (To be updated once module is formally released)

Required OpenMRS Versions

...

Downloads

Source at: https://github.com/openmrs/openmrs-module-webservices.rest
Download at: https://addons.openmrs.org/#/show/org.openmrs.module.webservices-rest

User Documentation

Visit https://rest.openmrs.org/#openmrs-rest-api for an overview of our Rest Documentation.

Required OpenMRS Version

The REST Web Services module requires at least OpenMRS 1.9.0 , or 1.8.1, 1 .7.2, or 1.6.3 to run.

Development Plans

Development sprint: 2011-05-16 Development Sprint

Alpha release of module coming soon.

Release Notes

( To be filled in once a formal release is made to the Module Repository )

...

Basic Configuration Options

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

Technical Documentation

The module exposes the OpenMRS API through light-weight resource objects off of the core OpenMRS objects. The structure is very similar, but not guaranteed to match up exactly.

This module uses Spring 3 annotations to expose URLs. Primary transport language is currently JSON and XML (beta in 2.1).

For Creators of Web Service Core/Module Methods

Adding a Web Service Step by Step Guide for Core Developers
Adding a Web Service Step by Step Guide for Module Developers

For Web Service Client Developers

See REST Web Services API For Clients

Development History

Initial project page: Enhanced Web Services (Design Page)
Development sprint 1: 2011-05-16 Development Sprint
Followup sprint: 2011-05-30 Development Sprint
Development sprint 2: 2011-07-05 Development Sprint
Development sprint 3: 2013-02-07 Integration of RESTWS

Example Client code

• Quick java swing client that displays patients and encounters: http://svn.openmrs.org/openmrs-contrib/examples/webservices/hackyswingexample/
• In the following link you can download a client (API) java that allows  add - edit a person (any resource) and make a query to Webservice.Rest https://project-development-software-victor-aravena.googlecode.com/svn/trunk/ClientOpenMRSRest/ 

Release Notes

• 2.14+
  • See JIRA for details
• 2.13 Released January 7th 2016
  • Add support for OpenMRS Platform 2.0.0 (beta)
  • And:
    

    Jira Legacy
    server OpenMRS JIRA columns key,summary,type,assignee,reporter,priority maximumIssues 1000 jqlQuery project = RESTWS AND fixVersion = 2.9 ORDER BY updated DESC, priority DESC, created ASC serverId 45c5771b-fa4b-3e43-b34a-c19dc45ccc95

• 2.12
  

  Jira Legacy
  server OpenMRS JIRA columns key,summary,type,assignee,reporter,priority maximumIssues 1000 jqlQuery project = RESTWS AND fixVersion = 2.9 ORDER BY updated DESC, priority DESC, created ASC serverId 45c5771b-fa4b-3e43-b34a-c19dc45ccc95

• 2.11
  

  Jira Legacy
  server OpenMRS JIRA columns key,summary,type,assignee,reporter,priority maximumIssues 1000 jqlQuery project = RESTWS AND fixVersion = 2.9 ORDER BY updated DESC, priority DESC, created ASC serverId 45c5771b-fa4b-3e43-b34a-c19dc45ccc95

• 2.10
  

  Jira Legacy
  server OpenMRS JIRA columns key,summary,type,assignee,reporter,priority maximumIssues 1000 jqlQuery project = RESTWS AND fixVersion = 2.9 ORDER BY updated DESC, priority DESC, created ASC serverId 45c5771b-fa4b-3e43-b34a-c19dc45ccc95

• 2.9 Released January 15th 2015
  
  

  Jira Legacy
  server OpenMRS JIRA columns key,summary,type,assignee,reporter,priority maximumIssues 1000 jqlQuery project = RESTWS AND fixVersion = 2.9 ORDER BY updated DESC, priority DESC, created ASC serverId 45c5771b-fa4b-3e43-b34a-c19dc45ccc95

  
   
• 2.8
• 2.7
  

  Release Date: Wednesday November 26th 2014

  2.7 represents version: 20afb1bcdbc46a75859e2c736a8651fa38614720
   

  A huge thank you goes out to the following contributors: Daniel Kayiwa, Darius Jazayeri, Jon Skeet, Pawe? Muchowski, Rafal Korytkowski, Willa Ahmed, Wyclif Luyima
  

  New Features

  • [RESTWS-453] - Expose login locations via REST
  • [RESTWS-455] - Add ConceptSearchResource
  • [RESTWS-457] - orderfrequency resource should have a representation that includes the full concept representation
  • [RESTWS-461] - Should automatically convert to Double
  • [RESTWS-463] - encounter resource should let you create real-time encounters without explicitly specifying encounterDatetime
  • [RESTWS-465] - Get inactive orders

  Bug Fixes

  • [RESTWS-451] - Nested custom type will fail with conversion exception
  • [RESTWS-454] - deathDate property should be editable on the person resource
  • [RESTWS-458] - orderfrequency resource should have display property
  • [RESTWS-464] - encounter resource has a typo that prevents creating an encounter with orders easily
  • [RESTWS-467] - Going to catalog API using JSON causes stack overflow due to subtypes
  • [RESTWS-469] - NPE generating catalog
  • [RESTWS-470] - Catalog incorrectly shows sub-resources
  • [RESTWS-471] - A resource implementing Listable without Searchable fails in MainResourceController
• 2.6

New Features

• • [RESTWS-281] - REST does not expose relationships or relationship_types
  • [RESTWS-444] - Add brandName and dispenseAsWritten to DrugOrderSubclassHandler1_10

Bugs

• • [RESTWS-426] - REST can return a Patient representation when we want a Person rep
  • [RESTWS-441] - User and concept search handlers do not work for OpenMRS 1.10
  • [RESTWS-442] - ProviderSearchHandler should handle OpenMRS 1.10

• 2.5
  

  Jira Legacy
  server OpenMRS JIRA columns key,summary,type,assignee,reporter,priority maximumIssues 1000 jqlQuery project = RESTWS AND fixVersion = 2.5 ORDER BY updated DESC, priority DESC, created ASC serverId 45c5771b-fa4b-3e43-b34a-c19dc45ccc95

• 2.4

  Image Added	RESTWS-371	There should be a way to create a patient in a single call
  Image Added	RESTWS-395	should be allowed to supply identifierType by uuid which creating patient
  Image Added	RESTWS-394	saving attributes on PersonResource fails with NullPointerException
  Image Added	RESTWS-397	Cannot search for numeric concept "full" representation
  Image Added	RESTWS-399	REST API for patient not returning person.personDateCreated
  Image Added	RESTWS-393	ConceptResource does not return full tree of its members
  Image Added	RESTWS-400	OrderResource1_8 does not have voided property in Default or Full Representation
  Image Added	RESTWS-401	Properties should be allowed to be set to null
  Image Added	RESTWS-396	Obs with 1 groupMember does not fetch the group members.
  Image Added	RESTWS-402	BaseRestController unnecessarily stores state
  Image Added	RESTWS-398	Support gender, birthdate, birthdateEstimated, addresses, attributes and names as updatable properties in PersonResource.

  
  

• 2.3
  • New Features
    
    • RESTWS-392 - APIAuthenticationException handler always adds WWW-Authenticate header when user is not logged in.
  • Bug Fixes
    • Changed setMembers to full representation
• 2.2
  • New Features
    
    • [RESTWS-348] - Require that user have View REST WS Menu privilege to view the menu in the administration page
    • [RESTWS-391] - Rest API to search drug by name
  • Bug Fixes
    
    • [RESTWS-373] - Incorrect Converter returned in ConversionUtil convertToRepresentation()
    • [RESTWS-381] - Return object representation instead of id for person attribute
    • [RESTWS-384] - restService.getSearchHandler fails with ClassCastException
    • [RESTWS-389] - Cannot set location person attribute with uuid
    • [RESTWS-390] - PersonAttributeTypeResource should render hydrated concept
• 2.1
  • Better XML support (backwads incompatibility, see RESTWS-206)
  • Replaced .../concept/<conceptname> with .../concept?name=<conceptname> (backwards incompatibility, see RESTWS-370)
  • Additional search handlers
  • Improvements to the catalog
• 2.0 (see Migration from REST 1.x to 2.x)
  • Integrated Webservices.rest 1.9 extension module
  • Removed controllers (single point of entry)
  • Added search handlers
  • Added support for Concept mappings
• 1.1
  • (23 bugs/features fixed/added)
  • Fixed concept.answers
  • Fixed patient.identifiers
  • Made more resources editable
  • Added ability to return retired resources generally
  • Added Provider and Visit support to the 1.9ext module
• 1.0
  • Main functionality realized with no new bugs
• 0.9 (Beta)
  • Bugfixes
• 0.8 (Alpha)
  • All use cases working as defined on the Web Service 1.0 User Stories page
  • Download omod to install in your own OpenMRS installation

Download standalone with webservices module for an out of the box openmrs with rest web services ready to go.