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:
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/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.
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.
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.
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
Recommended Comments
There are no comments to display.