REST API Overview

The JasperReports Server REST API is an Application Programming Interface that follows the guidelines of REpresentational State Transfer design to allow client application to interact with the server through the HTTP protocol. With a few exceptions, the REST API allows clients to interact with all features of the server, such as running, exporting, and scheduling reports, reading and writing resources in the repository, and managing organizations, roles, and users. The REST API requires credentials for every operation and enforces the same permissions and administrator restrictions as the server's user interface.

Client applications send requests to named URLs that are called services. A service provides several operations on a feature, for example the roles service lists the roles in an organization, gives the properties and members of a role, writes new roles, updates existing roles, and deletes roles. This chapter lists all the services of the current REST API. The other chapters of this API Reference each describe one of the services.

In order to describe resources and objects in the server, the REST API sends and receives data structures called descriptors. Most services support descriptors in both XML (eXtensible Markup Language) and JSON (JavaScript Object Notation). The descriptors are specific to each service, and are defined in the corresponding chapter of this reference. Descriptors are usually sent and received in the body of HTTP requests and responses, so your client application usually relies on further APIs to handle the HTTP communications.

Historically, the REST API is considered a web service, and JasperReports Server provided several other web services. The current REST API is the second version and all services use the rest_v2/ prefix. The first REST API with the rest/ prefix and the earlier SOAP API (Simple Object Access Protocol) are deprecated and no longer maintained. Although the server might still respond to deprecated services, they are not updated for new features of the server and are never garanteed to succeed or be accurate. For completeness, the deprecated service names are listed at the end of this chapter.

This chapter includes the following sections:

• List of Services
• Sending REST Requests from a Browser
• HTTP Response Codes
• Deprecated Web Services

List of Services

The REST API of JasperReports Server responds to HTTP requests from client applications, in particular the following methods (sometimes called verbs):

• GET to list, search and acquire information about server resources.
• POST to create new resources and execute reports.
• PUT to modify existing resources.
• DELETE to remove resources.

As with any RESTful service, not all methods (GET, PUT, POST, and DELETE) are supported on every service. The URLs usually include a path to the resource being acted upon, as well as any parameters that are accepted by the method. For example, to search for input control resources in the repository, your application would send the following HTTP request:

GET http://<host>:<port>/jasperserver[-pro]/rest_v2/resources?type=inputControl

In all URLs in this API Reference:

• <host> is the name of the computer hosting JasperReports Server
• <port> is the port you specified during installation
• jasperserver[-pro] indicates that the service is available in both Community and Commercial editions.
• jasperserver-pro indicates that the service is available only in Commercial editions.
• The context name (by default jasperserver or jasperserver-pro) may be customized in your specific installation of JasperReports Server

The REST services are available at the following URLs:

REST API Services and URLs

Web Service

URLs

Login (optional)

http://<host>:<port>/jasperserver[-pro]/rest_v2/login

http://<host>:<port>/jasperserver[-pro]/logout.html

http://<host>:<port>/jasperserver[-pro]/rest_v2/serverInfo

Repository

http://<host>:<port>/jasperserver[-pro]/rest_v2/resources

http://<host>:<port>/jasperserver-pro/rest_v2/domains/.../metadata *

http://<host>:<port>/jasperserver[-pro]/rest_v2/permissions

http://<host>:<port>/jasperserver[-pro]/rest_v2/export

http://<host>:<port>/jasperserver[-pro]/rest_v2/import

http://<host>:<port>/jasperserver[-pro]/rest_v2/keys

Reports

http://<host>:<port>/jasperserver[-pro]/rest_v2/reports

http://<host>:<port>/jasperserver[-pro]/rest_v2/reportExecutions

http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/.../inputControls

http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/.../options

http://<host>:<port>/jasperserver[-pro]/rest_v2/jobs

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts/{alertId}

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts?id={ID_1}&id={ID_2}&...&id={ID_n)

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts/pause/

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts/resume/

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts/restart/

http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts/calendars

http://<host>:<port>/jasperserver-pro/rest_v2/queryExecutor *

http://<host>:<port>/jasperserver-pro/rest_v2/caches/vds *

Administration
without
organizations

http://<host>:<port>/jasperserver[-pro]/rest_v2/users

http://<host>:<port>/jasperserver[-pro]/rest_v2/users/.../attributes

http://<host>:<port>/jasperserver[-pro]/rest_v2/roles

http://<host>:<port>/jasperserver[-pro]/rest_v2/attributes

Administration
with
organizations *

http://<host>:<port>/jasperserver-pro/rest_v2/organizations

http://<host>:<port>/jasperserver-pro/rest_v2/organizations/.../attributes

http://<host>:<port>/jasperserver-pro/rest_v2/organizations/.../users

http://<host>:<port>/jasperserver-pro/rest_v2/organizations/.../users/.../attributes

http://<host>:<port>/jasperserver-pro/rest_v2/organizations/.../roles

http://<host>:<port>/jasperserver-pro/rest_v2/attributes

* Available only in commercial editions of JasperReports Server.

For progammers creating a client application, the reference chapters in this guide give the full description of the methods supported by each REST service, the path or resource expected for each method, and the parameters that are required or optional in the URL. The description of each method includes an example of the descriptors it uses and a sample of the return value.

For tools that can parse the Web Application Description Language (WADL), the following URL gives a machine-readable XML description of all supported REST v2 services:

http://<host>:<port>/jasperserver[-pro]/rest_v2/application.wadl

Sending REST Requests from a Browser

Normally, you program your client application to send REST requests to your instance of JasperReports Server. You may also want to test certain requests or examine the response from the server, and some browsers have plug-ins to send a REST request and view the response.

However, the server includes cross-session request forgery (CSRF) protection that does not allow requests, including REST, from a browser in a different domain. Sending POST, PUT, or DELETE requests from a browser will often fail for this reason. REST requests from REST-client applications are secure and are not stopped by CSRF protection.

To allow testing of the REST API through a browser, configure your browser REST client to include the following header in every request:

X-REMOTE-DOMAIN: 1

HTTP Response Codes

JasperReports Server REST services return standard HTTP status codes. In case of an error, a detailed message may be present in the body as plain text. Client error codes are of type 4xx, while server errors are of type 5xx. The following table lists all the standard HTTP codes. Each service returns typical success and error messages that are given in the reference chapter for that service.

HTTP Response Codes

Success Messages

Client Error

Server Errors

Code

Message

Code

Message

Code

Message

100

Continue

400

Bad Request

500

Internal Server Error

101

Switching Protocols

401

Unauthorized

501

Not Implemented

200

OK

402

Payment Required

502

Bad Gateway

201

Created

403

Forbidden

503

Service Unavailable

202

Accepted

404

Not Found

504

Gateway Time-out

203

Non-Authoritative Information

405

Method Not Allowed

505

HTTP Version Not Supported

204

No Content

406

Not Acceptable

 

 

205

Reset Content

407

Proxy Authentication Required

206

Partial Content

408

Request Time-out

300

Multiple Choices

409

Conflict

301

Moved Permanently

410

Gone

302

Found

411

Length Required

303

See Other

412

Precondition Failed

304

Not Modified

413

Request Entity Too Large

305

Use Proxy

414

Request URI Too Large

307

Temporary Redirect

415

Unsupported Media Type

 

416

Requested Range Not Satisfiable

417

Expectation Failed

Deprecated Web Services

The server's first REST API (now called v1) is deprecated. These services are no longer supported, do not work with the latest features of the server, and are never guaranteed to succeed. Note that meanings of PUT and POST were reversed in the REST v1 API.

Deprecated REST v1 Services

Web Service

URLs

Login

http://<host>:<port>/jasperserver[-pro]/rest/login

http://<host>:<port>/jasperserver[-pro]/j_spring_security_check

http://<host>:<port>/jasperserver[-pro]/GetEncryptionKey

Repository

http://<host>:<port>/jasperserver[-pro]/rest/resources

http://<host>:<port>/jasperserver[-pro]/rest/resource

http://<host>:<port>/jasperserver[-pro]/rest/permission

Reports

http://<host>:<port>/jasperserver[-pro]/rest/report

http://<host>:<port>/jasperserver[-pro]/rest/jobsummary

http://<host>:<port>/jasperserver[-pro]/rest/job

Administration
without
organizations

http://<host>:<port>/jasperserver[-pro]/rest/user

http://<host>:<port>/jasperserver[-pro]/rest/attribute

http://<host>:<port>/jasperserver[-pro]/rest/role

Administration
with
organizations *

http://<host>:<port>/jasperserver-pro/rest/organization

http://<host>:<port>/jasperserver-pro/rest/user

http://<host>:<port>/jasperserver-pro/rest/attribute

http://<host>:<port>/jasperserver-pro/rest/role

* Available only in commercial editions of JasperReports Server.

The original SOAP web services at the following URLs are also deprecated and no longer supported. The SOAP web services will no longer be maintained or updated to work with new features of the server. In particular, the SOAP web services do not support interactive charts or interactive HTML5 tables. Though the server may still respond to these methods, they are never guaranteed to work.

The SOAP web services often refer to the http://www.jasperforge.org/jasperserver/ws namespace. This namespace is only an identifier; it is not intended to be a valid URL.

Deprecated SOAP Web Services

Edition

Web Service

URL

Community Project

Repository

http://<host>:<port>/jasperserver/services/repository

Scheduling

http://<host>:<port>/jasperserver/services/ReportScheduler

Administration

http://<host>:<port>/jasperserver/services/UserAndRoleManagementService

Commercial Editions

Repository

http://<host>:<port>/jasperserver-pro/services/repository

Scheduling

http://<host>:<port>/jasperserver-pro/services/ReportScheduler

Domains

http://<host>:<port>/jasperserver-pro/services/DomainServices

Administration

http://<host>:<port>/jasperserver-pro/services/UserAndRoleManagementService