Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports Server REST API Reference. View the latest documentation.

    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)

    The following services use the rest/ prefix but are still supported as part of the REST API:

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

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

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

    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

    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.

    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

    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


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...