Reporting REST API (Design Page)
- Burke Mamlin
Owned by Burke Mamlin
May 09, 2016
2 min read
Loading data...
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