Bluemix Embedded Reports REST architecture

Question

When one wishes to use the Bluemix Embedded Reports one first creates a package and then a report definition. After that, one is supposed to use the REST APIs that are documented using Swagger here:

https://erservice-impl.ng.bluemix.net/ers/swagger-ui/

Unfortunately, I am unable to find any architectural definitions for these APIs. To elaborate on this notion, there are APIs to get connections, packages, definitions, reports, models, datasources and visualizations ... however I unable to find any documentation describing when I would use what. In addition, some fundamental APIs such as those relating to operations for "reports" seem to want a "reportId" and I am lost on how to retrieve or obtain one of those. Other mysteries are the concept of "What are report links?" and what is the semantics of obtaining a "report instance"? For a report "rendered in a format" ... what are the allowable formats and when would I use vs another?

Again ... the REST API isn't bad and Swagger provides useful syntax documentation but without the associated semantic comprehension, it leaves the reader cold on quite how to use the technology.

I am hoping that there is additional documentation either existing somewhere or else planned for release as soon as practicable. If anyone knows where to find such or has additional information on how to interpret the semantics of the APIs, that would be a fantastic answer to the question.

Answer 1

Some information around the REST API, particularly around running of reports, is available on the documentation page for the service, found here: https://console.ng.bluemix.net/docs/services/EmbeddableReporting/index.html#gettingstartedtemplate

Though the full API is provided in swagger, users are expected to use only 3 resources: connection , definitions , and reports . The other endpoints deal with the management of report artifacts and their related resources (datasources, models, packages)

The first step in using ERS is to define datasources and report specifications (definitions) within the admin dashboard. Then, each definition will be given an ID that you can copy/paste into your RESTful calls.

1. Connect to ERS using basic auth and the /connection endpoint. This sends back cookies (include a JSESSIONID) that you are expected to send with all other calls.

    POST /connection 

with an empty json body {} and basic auth headers

2. Run a report in a particular format (2 flavours)

   2.1 For 'vanilla' reports with no special options or parameters, you can use the shortcut call, which both creates a report resource and runs it in the format you choose:

    GET /definitions/{definition_id}/reports/{format} 

   where definition_id is taken from the admin dashboard, and format is one of html, phtml (partial html, for embedding. Most common), pdf, json, xml, csv

   2.2 For more complex cases, you need to first create a report instance (this holds state for the report that is being run. You can do a next-page or check parameter values and options). Then you can run the report in a format.

    POST /definitions/{definition_id}/reports 

   with a body with your options/parameters. You can also send an empty json body ({}) for all the defaults. This returns a json payload with a reportId and location to run the report from

    GET /reports/{report_id}/{format} 

You might also want to look at the sample that is included in the documentation (in javascript, java and node) to see how to do this in an app. The documentation mentioned above also has curl examples.