Page Comparison

{note}This is an old and no longer supported version. Please see [REST Module |docs:REST Module]for the latest version.{note}

h2. 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 to an OpenMRS database.

h2. Downloads

Source at [https://github.com/openmrs/openmrs-module-webservices.rest/tree/1.x |https://github.com/openmrs/openmrs-module-webservices.rest/tree/1.x]

Download at [https://modules.openmrs.org/modules/download/webservices.rest/webservices.rest-1.1.29293.omod]

Download OpenMRS 1.9.x extension module at [https://modules.openmrs.org/modules/view.jsp?module=webservices.rest19ext] (It is needed, if you are running OpenMRS 1.9.1 and want to access some of the new API methods, tables, and objects.)

h2. User Documentation


h3. Required OpenMRS Version

The REST Web Services module requires at least OpenMRS 1.9.0 or 1.8.1 to run.

h3. Configuration Options
{html}<dl>
<dt><b>webservices.rest.maxResultsDefault</b></dt>
<dd>This [Global Property|docs:Global Properties Descriptions] determines the maximum number of resources that can be accessed on any webservice call.&nbsp; The default is *50*.</dd>

<dt><b>webservices.rest.maxResultsAbsolute</b></dt>
<dd> This [Global Property|docs:Global Properties Descriptions] 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*.</dd>

<dt><b>webservices.rest.uriPrefix</b></dt>
<dd>This should point at the root of your exposed web application.&nbsp; This is typically <i>http://localhost:8080/openmrs</i> during testing, but after being deployed will be something like <i>http://192.168.1.100/openmrs</i> or <i>http://yourdomainname.org/openmrs</i>. If this is empty or not filled in, the user will see NEEDSTOBECONFIGURED/ws/rest/ as the "self" urls on all objects.</dd>

<dt><b>webservices.rest.allowedips</b></dt>
<dd>By default this is an empty string: "",&nbsp;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&nbsp;with bit masks to denote whole subdomains e.g. 10.0.0.0/30 matches&nbsp;10.0.0.0 - 10.0.0.3 and 10.0.0.0/24 matches 10.0.0.0 - 10.0.0.255.&nbsp;Non matching IP addresses will receive a 403 HTTP error. Both IPv4 and IPv6 addresses are supported.</dd>

</dl>{html}

h2. Technical Documentation

The module exposes the OpenMRS API through light-weight&nbsp;*resource*&nbsp;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 with XML to be added at a later date.

h3. For Creators of Web Service Core/Module Methods

[Adding a Web Service Step by Step Guide for Core Developers (REST 1.x)]
[Adding a Web Service Step by Step Guide for Module Developers (REST 1.x)]

h3. For Web Service Client Developers

See&nbsp;[REST Web Services API]

For more information on individual objects within the API, see&nbsp;[REST Web Service Resources in OpenMRS 1.8]

h2. Development History

Initial project page:&nbsp;[Enhanced Web Services (Design Page)|projects:Enhanced Web Services (Design Page)]
Development sprint 1: [2011-05-16 Development Sprint|RES:2011-05-16 Development Sprint]
Followup sprint: [2011-05-30 Development Sprint|RES:2011-05-30 Development Sprint]
Development sprint 2:&nbsp;[2011-07-05 Development Sprint|RES:2011-07-05 Development Sprint]

h2. Example Client code

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

h2. Release Notes

* 1.1
** ([23 bugs/features fixed/added|https://tickets.openmrs.org/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+RESTWS+and+fixVersion+%3D+%221.1%22])
** 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&nbsp;[projects:Web Service 1.0 User Stories]&nbsp;page
** [Download omod|https://modules.openmrs.org/modules/download/webservices.rest/webservices.rest-0.8.omod]&nbsp;to install in your own OpenMRS installation
** [Download standalone with webservices module|https://sourceforge.net/projects/openmrs/files/prereleases/OpenMRS_1.8.1_Web_Services_Alpha/]&nbsp;for an out of the box openmrs with rest web services ready to go.