Reporting REST API (Design Page)

Owned by Burke Mamlin
May 09, 2016
2 min read

Background

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.

Goals

  • 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

/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

/report/{uuid}/request/{uuid}
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)


/dataset

 

See Also