REST API Overview

Endpoints

ReportShell REST API provides the following endpoints:

• Input Controls: Retrieve input control metadata for a report, load input control data sets and evaluate latest states based on the final parameter values
• Executions: Manage persistent executions and retrieve print metadata
• Render: Export a report to a specific format (e.g. PDF, Excel, CSV)

These endpoints are designed to be similar to the JasperReports Server API to simplify the learning curve for users familiar with JRS.

Base Path

The base-path for all REST endpoints is <contextPath>/reportshell/api. Example URLs used in this page and other REST API pages assume you use them with this base-path.

Request Structure

Many ReportShell endpoints operate with both GET and POST requests. Parameters starting with prefix rs. (e.g. rs.locale) are reserved system parameters that affect the behavior of the endpoint. Other parameters are report parameters and they are bound to the report input controls.

Example GET request:

GET /v1/reports/{reportId}/render.pdf?rs.locale=en_US&rs.page=1&param1=value1&multiValueParam=value1&multiValueParam=value2

Example POST request:

POST /v1/reports/{reportId}/render.pdf
Content-Type: application/x-www-form-urlencoded

rs.locale=en_US&rs.page=1&param1=value1&multiValueParam=value1&multiValueParam=value2

When endpoints require a JSON request body such as the Executions endpoint, root level parameters are the system parameters (without the rs. prefix) and report parameters are nested under a parameters key.

Example JSON request:

{
  "locale": "en",
  "parameters": {
    "param1": "value1",
    "multiValueParam": ["value1", "value2"]
  }
}

Common Fill Parameters

These parameters affect how a report is filled and are used by all endpoints that run a report fill.

Parameter	Type	Description
rs.locale	String?	Locale identifier converted to a Locale object and set as the REPORT_LOCALE Jasper report parameter value when filling a report.
rs.timezone	String?	A valid timezone ID. Converted to a TimeZone object and set as the REPORT_TIME_ZONE Jasper report parameter value.
rs.null	String?	Parameter names to set to null. See Null Values below.
rs.ignorePagination	Boolean?	Whether to ignore pagination when filling a report. Set as the IS_IGNORE_PAGINATION Jasper report parameter value.
rs.extra.XXX	Map<String, String[]>?	User specific extra parameter map

Null Values

To explicitly send a null value for a report parameter in a GET request, use the rs.null parameter with the parameter names you want to set to null. E.g. rs.null=param1&rs.null=param2

In JSON requests, just use the null value.

{
  "parameters": {
    "param1": null
  }
}

Extra Parameters

Use rs.extra. prefix for your own application specific parameters. Such parameters can be multi valued.

Example URL:

?rs.extra.foo=bar&rs.extra.foo=baz&rs.extra.baz=zoo

These parameters are automatically copied into the operation context as an extra-parameter map. This allows you to pass application-specific values through the request lifecycle and access them from fill and export operations.

See Operation Contexts for more details about these concepts.

JSON Parameter Format

Because ReportShell REST API supports both JSON and form-urlencoded requests, it is recommended to send report parameter values as strings or arrays of strings in your JSON requests even if the control is of a different type such as Number.

ReportShell will convert the values to the appropriate type based on the control’s parameter type.

Example JSON request with system parameters:

{
  "locale": "en",
  "parameters": {
    "integerParam": "10",
    "numberParam": "10.5",
    "dateParam": "2022-01-01",
    "booleanParam": "true",
    "multiNumberParam": ["10", "10.5"]
  },
  "extra": {
    "foo": ["bar", "baz"],
    "baz": ["foo"]
  }
}

Caution

ReportShell REST APIs mainly support simple values and arrays of simple values. Conversion logic is JSON based and actually supports converting complex objects but there is no standard mechanism to represent complex objects as request parameters.

Unlike parameters object, extra object does not support simple string values. Make sure you always pass arrays of strings even for singular values.

Request Mapping and Report Keys

Most ReportShell REST API controllers receive the report key either as a URL path variable and support two request mapping variants:

1. /reports/{reportKey}/<action>
2. /<action>/{*reportKey}

The first variant supports single-segment keys (e.g., /reports/123/controls), where the key is a simple unique identifier like a database ID or UUID. The second variant uses the star (*) prefix to support multi-segment keys (e.g., /controls/sales/summary), where the key acts as a hierarchical path or slug.

Recent versions of the Spring Framework do not support multi-segment path variables in the middle of a URL pattern. Therefore, a single mapping strategy like /reports/sales/summary/controls is not feasible out-of-the-box. While you can implement custom mapping strategies or revert to deprecated Spring behaviors, those approaches are outside the scope of this documentation.