This document will serve as a beginners guide to RESTful webservices.
...
- 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,
- 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.