What this module does
The module exposes the OpenMRS API as REST web services. if an OpenMRS instance is running the Webservices.REST module, other programs (and languages) can connect to retrieve and post certain information through OpenMRS.
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:
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.
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.
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
For all features in the REST module to work you must use a nightly build of at least version 20404. This is due to
The REST Web Services module requires at least OpenMRS 1.9.0, 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 )
Module Configuration
webservices.rest.maxResultsDefault - This Global Property determines the maximum number of resources that can be accessed on any webservice call. The default is 50.
webservices.rest.maxResultsAbsolute - This Global Property determines the absolute maximum number of resources that can be accessed on any webservice call. If the client requests more than this limit, then receives an error. The default is 1000.
webservices.rest.uriPrefix - This should point at the root of your exposed web application. This is typically _http://localhost:8080/openmrs_ during testing, but after being deployed will be something like _http://192.168.1.100/openmrs_ or _http://yourdomainname.org/openmrs_. If this is empty or not filled in, the user will see NEEDSTOBECONFIGURED/ws/rest/ as the "self" urls on all objects.
webservices.rest.allowedips - By default this is "", which means anyone can access the rest URLs. If you put any IP addresses into this list, only calls from those are allowed. IPs should be separated by a whitespace or a comma. IPs can be declared with bit masks to denote whole subdomains e.g. 10.0.0.0/30 matches 10.0.0.0 - 10.0.0.3 and 10.0.0.0/24 matches 10.0.0.0 - 10.0.0.255. Non matching IP addresses will receive a 403 HTTP error. Both IPv4 and IPv6 addresses are supported.