Getting Started with REST Web Service API

Editors Note: Jaspersoft continues to expand and improve the functionality of the REST web services. This API allows client applications to interact with most features of the server over HTTP using standard XML and JSON objects. With the completion of the v2 REST API, Jaspersoft announces the deprecation of the original REST API and the end-of-life of the SOAP services. While these services will remain available in the server for the time being, Jaspersoft recommends that you migrate your integration to the latest API available: Jaspersoft v2 REST API.

Getting started with REST Web Service API

Starting with version 4.2, the JasperReports Server can be accessed through a new Web Service API based on the REST framework. The goal of Jaspersoft is to provide two equally powerful web service APIs (namely the SOAP and REST APIs) to integrate the functionality of the JasperReports server inside your application.

This article introduces the Jaspersoft REST Web Service API, highlights the key features and then shows how you can use the REST API to integrate the JasperReports server in your application.

Please feel free to contact the Jaspersoft product team at product_team@jaspersoft.com if you have any questions or feedback on this article.

Introduction

The REST (REpresentational State Transfer) Web Services API is a new set of APIs built on the RESTful framework to programmatically perform server operations. This REST API relies on a stateless, client-server, cacheable communications protocol and uses the HTTP protocol to interact with the JasperReports server.

Difference between REST and SOAP Web Service APIs

The flow chart below shows the how the SOAP and REST APIs work with the request, process the data and finally return the response to the client.

The architectures for the two API are quite similar. The big difference is how the REST approach simplifies the process of interacting with the API. The calling application does not need to build an XML string to contain the request. The requirement for the XML string in SOAP puts an additional burden on the application both in terms of development time and performance during the execution of the API code.

Features of the REST API

The REST API was launched in version 4.2 of the Jaspersoft BI suite. This initial release contains the interface to the repository service. The following services are available in the REST API in version 4.2:-

• resources - For listing and searching for resources in the repository.
• resource - For getting detailed information about a resource, creating a resource, modifying it or deleting it, depending on the HTTP method used.
• report - For running a report, specifying an export format, and downloading the report output.

Refer to Chapter 2 of the Jaspersoft REST APIs guide for more information on how to use the REST APIs.

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.

Please, visit below documentation for details:

Deprecated Web Services

Deprecated SOAP Services

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.
Please visit this Link for details.

Choosing the right API

It depends on what you want to do with the APIs. You might even choose to use both the APIs in your application to cater to different use cases. Here are some of the criteria that will help you to decide which API to use:-

• Features - You should first check the Jaspersoft Web Services Guide to ensure that the desired functionality is available in the API you want to use. If the desired functionality is available in both the SOAP and REST APIs, then the following criteria will help you make a decision.
• Ease of Development - The calls to the REST API are much easier to code as they do not require the calling application to create an XML string to contain the request. A REST call is quite simply a URL call. This makes it easier to use the REST APIs when development time is at a premium and you need to get your application up-and-running quickly. For this reason, REST is the preferred framework in most modern applications.
• Platform Support - REST API is platform-agnostic and does not rely on the application architecture as all requests are sent using the standard HTTP protocol. On the other hand, support for SOAP varies in different platforms/application servers and so, there might be inconsistency in the functionality based on how your platform has implemented the SOAP specifications.
• Custom requirements - Your environment might have some specific requirements that play an important role in deciding the API you use:
  1. WS-Security - HTTPS is the standard protocol to implement security for both SOAP and REST. However, that level of security might not be adequate for some types of applications and the WS-Security extension for SOAP might be a mandatory requirement for that application.
  2. ACID Transactions - If your application needs ACID transactions over a service, you will have to use the SOAP API. While the REST framework supports transactions, it is not as comprehensive as SOAP and is not ACID compliant. This transactional reliability requirement is only very rarely seen in some enterprise applications.

Calling the REST API

You would essentially call a URL and pass the necessary parameters to that URL. This URL call can be made in any application language that supports the HTTP protocol including Java, PHP, .Net, Objective-C etc. The URLs should be of the following structure:-

 http://{host}{:port}/{jasperserver context}/rest/{service name}

For Example, if you wanted to list all the resources in the "/salesreports" folder on a JasperReports server running on your local machine, you would call: - http://localhost:8080/jasperserver/rest/resources/salesreports

Example

Download the sample application attached below
Pre-requisites:
Java, Maven, JasperReports server (version 4.2 or later)

Executing the Code Sample:

1. Extract all the files from the downloaded zip file to your file system.
2. Check the parameters at "srcmainjavacomjaspersoftjasperserverrestsampleConsts.java" to verify that the REST API can connect to your JasperReports server instance. Edit the file, if needed.
3. Ensure that the JasperReports server instance is running.
4. Run the following Maven command in the command prompt window - "mvn test".

restapicodesample.zip