OpenMRS software development is moving towards building web components that can work with each other, instead of being part of the Java module framework. Since the release of the webservices.rest module, we have focused on improving the REST resources so that we have a complete API that is accessible over HTTP and developers with different language skills can contribute. This tutorial will provide instructions on how to use the OpenMRS REST API to build custom user interfaces using modern/popular tools. Most efforts in the community have focused on using AngularJS, and we'll showcase some of the "best practices" in AngularJS development.

1. AngularJS & REST Web Services
#OMRS15
Darius Jazayeri
darius@openmrs.org
djazayeri@thoughtworks.com

2. Download this...
● Download the Postman Chrome app
● https://www.getpostman.com/
● We'll use it shortly

3. REST
● REST = Representational State Transfer
● the software architectural style of the World Wide Web
● Levels of maturity
– “just add a REST API on top of it”
– Hypermedia as the engine of application state (HATEOAS)
– http://martinfowler.com/articles/richardsonMaturityModel.html
● Using HTTP to interact with the server in a constrained
machine-friendly way
● Constraints allow for scalability via standard web
technologies (stateless, cacheable, layered)

4. REST concepts
● Resource
– URI that addresses a collection or item in the system
– e.g. http://…/patient or http://…/patient/abc123
● Representation
– Specific state of the application. Based on one of these a client
can change application state
– Typically JSON or XML
● Hyperlinks
– what client can do from a given state
– e.g. {"rel": "next", "uri": "http://.../concept?startIndex=50"}

5. REST in OpenMRS
● Started in 2011
● Level 2 on the Richardson Maturity Model
– http://martinfowler.com/articles/richardsonMaturityModel.html
● RESTful CRUD access to the OpenMRS
platform data model
● We would like to be REST-first, but we're not
there yet. This is still second-class to our Java
API

6. REST in OpenMRS
● Documentation on the wiki at “REST Web Services
API For Clients”
– https://wiki.openmrs.org/x/P4IaAQ
– Big refresh coming in the next OpenMRS Platform release
(Swagger!)
● Basic Authentication
● Paging
● Different sized representations (ref, default, full)
– Also, custom representations

7. REST in OpenMRS: Let's play
● Use the Postman Chrome app (or something
else)
● http://demo.openmrs.org/openmrs/ws/rest/v1/concept
● .../concept?startIndex=50
● .../concept?q=malaria
● .../concept/CIEL:160152
● Add header… Accept: application/xml
● .../location?v=default

8. REST in OpenMRS: Exercise
● Create an encounter for an existing patient that
records their weight
– You will need to find a patient, look up some other
metadata, and figure out the encounter POST
format

9. AngularJS
●
https://angularjs.org/ (by Google)
– “HTML is great for declaring static documents, but it falters when we try to use it for declaring dynamic
views in web-applications. AngularJS lets you extend HTML vocabulary for your application. The resulting
environment is extraordinarily expressive, readable, and quick to develop.”
● Great framework for building client-side web applications
● Normally, one would build a complete app in AngularJS
– Bahmni
– OpenMRS Ebola Tablet App
● In the OpenMRS Reference Application we embed smaller AngularJS apps in a primarily-
server-side application
– but we're using AngularJS more and more
●
Clone: https://github.com/djazayeri/openmrs-module-angulartutorial
openmrs-core version 1.11.x
modules: appui, uiframework, appframework, uicommons, webservices.rest

10. AngularJS Concepts
● Directives
– Think of this as an “HTML tag/attribute handler”
– AngularJS code that is applied
– Built-in directives; Also write your own
● Scopes
– The dynamic thing that connects controller to view
– Directives have a $scope (sometimes inherited from a
parent, sometimes isolated)
– $rootScope

11. AngularJS Concepts
● Two-way data binding
– <input ng-model="myVariable" type="text"/>
– Editing the text box will update $scope.myVariable
– Setting $scope.myVariable will update the text box
● Templates
– with {{ interpolation }}
● Functions in the $scope
– <button ng-click="doSomething()">...</button>
● See example1 in the tutorial module

12. AngularJS Docs
● Developer Guide
– https://docs.angularjs.org/guide
● API Reference
– https://docs.angularjs.org/api
● More sophisticated: tutorial example2

13. AngularJS Magic
● Tutorial example3

14. AngularJS +/- GSP
● OpenMRS Reference Application includes a
non-standard mix of server-side GSP and
client-side AngularJS code
● Filters
– {{ visit.startDate | date }}
● tutorial example4

15. AngularJS + REST in OpenMRS
● Using raw $http
– Tutorial example5
● Using ngResource
– Tutorial example6
● Services in uicommons module