Migration from REST 1.x to 2.x

Owned by raff
Last updated: Mar 25, 2013Version comment
2 min read

Let's start with a short comparison of Webservices.rest 1.x and Webservices.rest 2.x:

  1. 2.x supports OpenMRS 1.9 without installing the Webservices.rest 1.9 extension module, which was needed when using 1.x.
  2. 2.x exposes the same resources as 1.x and preserves the JSON format, but adds a better support for Concept mappings.
  3. 2.x has a single controller, which serves all resources. You do not have to create controllers for your custom resources as it was in 1.x.
  4. The 2.x @Resource annotation includes name, supportedClass, supportedOpenmrsVersions and order in comparison to 1.x which only had value (name).
  5. The 2.x @SubResource annotation includes parent, path, supportedClass, supportedOpenmrsVersions and order in comparison to 1.x which only had parent and path.
  6. 2.x reorganizes java packaging of resource classes and class names to include a corresponding version of OpenMRS i.e. 1_8 or 1_9.
  7. 2.x introduces new SearchHandlers, which allow you to implement custom searches for any resource.
  8. 2.x tests resources by accessing actual URLs instead of controller methods.
  9. 2.x is now officially supported version of the Webservices.rest module. We will not add new features or fix bugs in 1.x.

If you didn't implement any custom resources or subresources and you were just a consumer of JSON, the migration will not require from you any work other than uninstalling 1.x and installing 2.x. We have not changed any resources aside from Concept, which only received one new property for mappings. We also corrected a path for the location resource in OpenMRS 1.9, which was wrongly exposed at /rest/ws/v2/location instead of /rest/ws/v1/location.

If you did implement custom resources in your own module, then you will have to adjust to new packaging, resource/subresource annotations and remove resource controllers. It is pretty straightforward, yet it can be tedious depending on how many custom resources you have.

Let's consider a specific example. We want to move ObsResource to 2.x. You need to start from changing dependencies in your poms and creating a single controller to define your module namespace. See Adding a Web Service Step by Step Guide for Core Developers.

  1. Open ObsResource.java and remove @Handler. Change the resource annotation to @Resource(name = "obs", supportedClass = Obs.class, supportedOpenmrsVersions = { "1.8.", "1.9." }). Fix imports if any.
  2. Open ObsController.java. You can see that it has two custom search methods. Create ObsSearchHandler implementing SearchHandler, which can do the same searches depending on which request parameter is given. The alternative is to implement searches directly in the resource by overriding the doSearch method. We recommend SearchHandler as it is more robust.
  3. Remove ObsController.java. It is no longer necessary since all requests are handled by the main controller and you moved custom searches to ObsSearchHandler.
  4. If you had ObsControllerTest.java which called ObsController methods, then you need to change it to extend MainResourceControllerTest and call newGetRequest, newPostRequest or newDeleteRequest with the correct URL. See the new ObsController1_8Test.java for example.

That's it! Let us know if you have any questions.