Asynchronous RestFul Web-Service Endpoints

Owned by Former user (Deleted)
Last updated: Aug 23, 2012Version comment
4 min read

This document will serve as a beginners guide to RESTful webservices.

  • What are webservices?
    • Web services are client and server applications that communicate over the World Wide Web. As described by the World Wide Web Consortium (W3C), web services provide a standard means of interoperating between software applications running on a variety of platforms and frameworks. Web services are characterized by their great interoperability and extensibility, as well as their machine-processable descriptions, thanks to the use of XML. Web services can be combined in a loosely coupled way to achieve complex operations. Programs providing simple services can interact with each other to deliver sophisticated value-added services.

    • Benifits of web services
      • Loosely coupled (easily interchangeble)
      • Platform independent
      • xml based (easily readable)
      • Easier for machines to comprehend than ordinary web interfaces.

  • More about web services can be found here
  • What are REST (Representational State Transfer) webservices ? 

 REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines. RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.
 

  • Much like Web Services, a REST service is:
    • Platform-independent (you don't care if the server is Unix, the client is a Mac, or anything else),
    • Language-independent (C# can talk to Java, etc.),
    • Standards-based (runs on top of HTTP) 
  • How simple is REST ? see here  
  • The benifits of using RESTful services are -
    • Less overhead (no SOAP envelope to wrap every call in)
    • More human readable and testable (harder to test SOAP with just a browser)
    • Don't NEED to use XML
  • Restful web services in OpenMRS
    • The OpenMRS webservices.rest 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. 
  • How to build a module which re-uses the webservices.rest code.
    • Extending on the webservices.rest module is relatively easy. For more information, refer to the idgen.ws module, which exposes a rest url on the server running idgen that allows for remote sites to ping the server to get a new identifier.
    • Restful behavior of the SHR Adapter module
    • The SHR module was designed to depend on the webservices module, and expose restful webservices to the consumers
      • The module depends on the webservices.rest module
      • It follows all RESTful conventions defined by OpenMRS
      • It is compliant with future changes that the webservices.rest module may undergo
    • Differences. How and why
      • Restful webservice GET requests target a resource (encounter resource, concept resources, etc). In our case, it hits an controller class which retrieves the resources we need.
      • why ?
        • We need to retrieve one or several encounters by filtering based on certain parameters.
        • However, the url resources currently published by the webservices.rest module don't support our use case.
        • we could of course write up our custom resources to retrieve the results we need. But, OpenMRS currently supports only three representation types - ref, default and full. it would not allow us to supply multiple parameters as we need to do in order to support our use cases. To create an additional representation type includes making major changes to the webservices .rest api, which would make it uncompatible with future work done on the module. Considering that many improvements are being done on the webservice.rest module, this is not satisfactory.
        • Alternatively, we may use the the existing representations to get all encounters, and then filter them per our requirements. However, this would use an excessive ammount of resources, and result in a lot of unnessesary data being retrieved.
        • The webservices.rest module returns a single object. We are retrieving a number of objects, generating a result out of them, and and returning the result. 
        • Even full representations of webservices.rest module sometimes return default descriptions of underlying properties. Etc. the PersonResource. Others return representations of subresources. For example, the full version of the EncounterResorce returns a reference to its patient object.
      • Other limitations
        • The webservices.rest api makes generous use of the objects' uuid. This servely limits our ability to process objects, since we need to filter data using multiple Identifiers such as NID, EPID, ECID, FOSAID etc.
        • Using webservices to retrieve such objects would result in the need to employ multiple GET requests - one request to find the uuid, and a second request to  retrieve the object specified by the uuid.
        • Furthermore, the webservices.rest module is built as a mode of retreiving OpenMRS objects, but we need to do extensive processing of our objects within the module itself. Much of these proccessing requires us to use the OpenMRS api.
        • The default output mode of the webservices.rest module is JSON. Changing this to support xml means bypassing much of the benifits of re-using the rest module.
      • For these reasons, the SHR Adapter module uses the OpenMRS to retrieve / filter objects beneath its restful front end. However, the module is fully restful from the viewpoint of an external observer. However,