Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

This project is assigned to the OpenMRS 1.9 release milestonewas the project page used while designing the Module. See that module's documentation for the most up-to-date information


OpenMRS has an explicit API which has not been cleanly or explicitly exposed through web services.  We have a REST module and SOAP-based module(s) where folks have done work in the area.  We need a clear and explicit strategy for supporting web services.



  • A single OpenMRS module to support the core web service needs. 

Heavyweight vs. lightweight objects? This is similar to's approach. We could consider small & big versions objects OR consider having a standard object with the option to list additive properties (e.g., custom object).

Based on Canada's experience with WS, Returning a "summary" of objects in a list may lead to a chatty interaction.

Look at Google Charts.

Consider that we may want to support both publish & subscribe – i.e., OpenMRS may

Some notes here:

SOAP Style

  • Annotations to generate web services
Gliffy Diagram
nameWebservices DTO

Encounter DTO

  • uuid
  • datetime
  • encounter type (required)
    • required: uuid or name
  • location (optional)
    • required: uuid or name
  • patient (required)
    • required: uuid or identifier
    • optional: names
  • provider (required)
    • required: uuid
    • optional: identifier, names
  • observations (optional)
    • required: datetime, question concept uuid, answer (e.g., string, number, concept uuid, ...)
  • forms (optional)
    • required: uuid
    • optional: form name
  • orders (optional)


  • Base web services are in a module
  • We want to be able to support web services without needing to see/use the html page in the web application browser -- e.g., someone writing a PHP application could install the API + web service support by, for example, having an embedded jetty + h2 and making calls to the right port.

Do we want to use DTOs at the API level?

  • This module will follow a RESTful approach
  • The framework should allow new web service methods to be added with minimal effort
  • At this point, we can leave the Java objects with Hibernate magic (all object properties assumed to exist) and

Changes to the API

  • Eliminate the "magical save" -- i.e., editing an object in any context should not make/persist changes to the database.  This should *always* require a save method call.
  • Have an explicit approach for how "stubs" (e.g., new Concept(123)) can be used


  • Web services will need methods that allow for a list of desired properties to be defined at the time of getting an object to determine which "optional" properties are realized in the objects returned.
Code Block

// something like this:
ws.getPatient(123) // default
ws.getPatient(123, [includeProperties: ["preferredName", "birthdate", "gender"]])
  • No cascading saves -- i.e., properties of objects that are sets are read-only and will require separate method(s) to modify them.


API Service and Object Design

Action Plan

  1. Web services will be developed as an augmentation to the existing API... that is, we will not rewrite the current API and then expose them as web services... we will write the web services as an independent activity, hoping that they inform the further maintenance and redevelopment of the existing API.
  2. We will use CXF as the framework.
    1. See ?Webservices.cxf Module

Assigned Developer(s)

?Saptarshi Purkayastha

  1. Support OAuth or an equivalent authentication scheme
  2. An upcoming web services sprint is scheduled. See Development Sprints and the ws sprint page: 2011-05-16 Development Sprint

Interested Parties and Mentors

?Ben Wolfe (mentor)

Burke Mamlin

Darius Jazayeri

Saptarshi Purkayastha

See Also

Result / Output

See the REST Module for the documentation and final output.