REST API

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

  • 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.

REST API uses the OAuth2 protocol for authentication.

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.