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

This guide walks a module developer through adding a new set of web service methods for a core object. There is a separate guide for core developers.

Conventions

The first thing to do is to read through the conventions section on the REST Web Services API For Clients page. Your module should follow similar conventions.

Note: When creating a REST resource and sub-resource URI and name respectively, the absolute and relative path names should be written in all-lowercase ASCII letters. Avoid capital letters, camel caps to mention a few. The norm is to use lower case letters.

Examples:

/ws/rest/**/conceptclass
/ws/rest/**/yourmoduleid/yourresourcename

Getting the REST Web Services Jar into your project

See Requiring another module in your module

You will need to check out the webservices.rest project and mvn clean install it to make it available to your module project. You will also need to add a few dependencies in your module's pom.xml files:

main pom.xml file additions

<dependency>
<groupId>org.openmrs.module</groupId>
<artifactId>webservices.rest-api</artifactId>
<version>1.0</version>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.openmrs.module</groupId>
<artifactId>webservices.rest-omod</artifactId>
<version>1.0</version>
<scope>provided</scope>
</dependency>

omod project pom.xml file additions

<dependency>
  <groupId>org.openmrs.module</groupId>
  <artifactId>webservices.rest-api</artifactId>
</dependency>

<dependency>
  <groupId>org.openmrs.module</groupId>
  <artifactId>webservices.rest-omod</artifactId>
</dependency>

Note that some of the controller dependencies (e.g. BaseCrudController) are now part of package org.openmrs.module.webservices.rest.web.v1_0.controller.

Adding new Web Service URLs

Our best-practices may change over the course of the sprint as we learn new things, but see the reportingrest module for an example module exposing web services.

The documentation on how to create methods is the same as for the core developers. See that page for more information.

The only difference is that on your controller you will use

@RequestMapping(value = "/rest/yourmoduleid/yourobjectid")

Examples

The idgenws module was built as an example maven module that uses the restws code. It is a rudimentary example and does not use a lot of the helper parent classes. See http://svn.openmrs.org/openmrs-modules/idgenws/trunk

The reportingrest module was also built as a PoC. It is based on ant/build.xml and so the library setup, etc is slightly different than the maven example on this page. See the code for that here: http://svn.openmrs.org/openmrs-modules/reportingrest