REST API

The Reports add-on REST API provides the following functions:

  • Getting a list of reports.

  • Getting the details on a specific report.

  • Running a report and getting the result.

  • Getting the details on a specific report group.

  • Getting Swagger documentation.

Reports REST API uses the OAuth2 protocol for authentication in the same way as Generic REST.

To enable REST API for reports, make sure your build.gradle contains the following dependencies:

implementation 'io.jmix.reports:jmix-reports-rest-starter'
implementation 'io.jmix.security:jmix-security-oauth2-starter'

To make a report available through the REST API, select the Visible for REST API checkbox on the Report structure tab:

visible for rest
Figure 1. Visible for REST API checkbox

Below we provide a formal description of some features specific to Reports add-on. For more information on how to get an OAuth token and other REST API features, see REST API add-on documentation.

Getting Reports List

The list of existing reports can be retrieved with the following GET request:

/rest/reports/report

For example:

GET http://localhost:8080/rest/reports/report

Authorization: Bearer j-Rn3PPAiH7cZZfaDiDWQEDp9YU
Content-Type: application/json

The response body will contain the list of brief information on the reports marked as Visible for REST API:

[
    {
        "id": "cb090350-2694-e2bb-f5d9-813daa8dc418", (1)
        "name": "booksAvailability(xlsx)",(2)
        "code": "BOOKS_AVAIL",(3)
        "group": "4e083530-0b9c-11e1-9b41-6bdaa41bff94"(4)
    },
    {
        "id": "d8c7f4c5-2dd7-c7f1-7286-f8dd286d2603",
        "name": "LiteratureTypes(csv)",
        "group": "4e083530-0b9c-11e1-9b41-6bdaa41bff94"
    }
]
1 Report ID,
2 Report name,
3 Report system code (if exists),
4 Group ID.

Getting Report Info

The detailed information on a specific report is retrieved with the following GET request:

/rest/reports/report/{id}

The last part of the query here is the report identifier, for example:

GET http://localhost:8080/rest/reports/report/cb090350-2694-e2bb-f5d9-813daa8dc418

The returned JSON object will contain the following information on the passed report:

{
  "id": "cb090350-2694-e2bb-f5d9-813daa8dc418",
  "name": "booksAvailability(xlsx)",
  "code": "BOOKS_AVAIL",
  "group": "4e083530-0b9c-11e1-9b41-6bdaa41bff94",
  "templates": [
    {
      "code": "DEFAULT",
      "outputType": "XLSX"
    }
  ],
  "inputParameters": []
}

Running Report

To run a report, send the following POST request:

/rest/reports/run/{id}

The last part of the query here is the report identifier, for example:

POST http://localhost:8080/rest/reports/run/2dd27fbf-8830-416a-899f-339543f8f27a

The report parameters are passed in the request body:

{parameters: [{name: 'author',value: '4b3a21b0-d6b7-4161-b0b6-55f118fbaac5'}]}

To print a report with a non-default template, pass the template code in the request body:

{template: 'Template_1', parameters: [{name: 'author',value: '4b3a21b0-d6b7-4161-b0b6-55f118fbaac5'}]}

Getting Report Group Info

The detailed information on a specific report group is retrieved with the following GET request:

/rest/reports/group/{groupId}

The last part of the query here is the group identifier, for example:

GET http://localhost:8080/rest/reports/group/4e083530-0b9c-11e1-9b41-6bdaa41bff94

The returned JSON object will contain the following information on the passed group:

  • group ID

  • group title

  • group code (if exists)

{
  "id": "4e083530-0b9c-11e1-9b41-6bdaa41bff94",
  "title": "General",
  "code": "ReportGroup.default"
}

Getting the OpenAPI Documentation

The complete OpenAPI documentation on the reports add-on can be retrieved with the GET request on the address:

http://localhost:8080/rest/reports/docs/openapi.json
http://localhost:8080/rest/reports/docs/openapi.yaml

When fetching openapi.yaml from the server, the response returns application/yaml content type, so in you should use Accept: application/yaml in request header.