Reporting REST API (Design Page)

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

Projects

Reporting REST API (Design Page)

Analytics

Background

Goals

Design Ideas

See Also

Related content