Reporting REST API (Design Page)


The reportingrest module was created "long ago" when Darius Jazayeri and Ben Wolfe were working with Pentaho and before the OpenMRS REST API was realized. Per Darius Jazayeri: "it works, but probably not with the 'right' RESTful API." Reporting's REST API does not have its own JIRA project. Any REST-related work for reporting has been done in the REPORT project.


  • An intentionally-designed, externally-usable format for report definitions (e.g., a well-described JSON format)
    • Historically, the reporting framework has used XStream heavily to serialize objects. We'd like to move away from using serialized auto-generated XML of Java classes for definitions, perhaps toward a more formal, standard, and nicer format for defining reports.
  • TBD

Design Ideas



/report?download=true vs. /report/{uuid}/raw or /report/{uuid}/download (get URL from /report/{uuid} resource)

/report/{uuid}/request (or "run")
list of prior/current requests

status ± link to download

/query (e.g., cohort)
question: would we want /query?type=cohort, or to have /cohort (cohortdefinition, encounterquery, ...)

Darius: I would expect resources for cohortquery, encounterquery, obsquery, etc (not one single "query" resource, and also not one resource for every query implementation, like "gendercohortdefinition")

Mike: you need to be able to *both* create a new definition (e.g. persist it to the DB) and *also* execute a query based on a definition

GET /patientquery => lists saved cohort queries

POST /patientquery => creates a new cohort query (persists it to the DB)

GET /patientquery/{uuid}/request => list available runs of this query that I could download (or, are still in progress)

POST /patientquery/{uuid}/request => asynchronously execute a new run of this query

GET /patientquery/{uuid}/request => list available requests/runs of this query

GET /patientquery/{uuid}/request/{uuid} => get result of a specific request/run of this query

POST /patientquery/{uuid}/execute => synchronously execute a new run of this query

POST /patientquery/request => execute a new run of a (dynamically-defined) cohort query by its definition (asynchronous, instantly returns a link to the request)

POST /patientquery/execute => execute a new run of a (dynamically-defined) cohort query by its definition (synchronous, returns actual result, after a while)

Burke: "execute" is bad because it's an action verb, not a resource name

/data (e.g., calculation)



See Also