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 Web Services guide for more information on how to use the REST APIs.  

REST API Feature roadmap

Jaspersoft plans to enhance the REST APIs to not only bring it up to feature parity with the SOAP APIs but also to add support for more server operations using web services. The following features are planned for the next product release targeted for late 2011:-

  • Support for the other services present in the SOAP API - Add the Report Scheduling, Domain and Administration services.
  • Ability to create/update/delete domains - The SOAP API provides only read-only access to domains using web services. Using the REST APIs, you will be able to programmatically create new and update existing domains.
  • Create/Update dashboards - You can assemble dashboards from report units using the REST web services API calls.
  • Add/Update/Delete Report Options - The REST API can be used to add/modify/delete various report options such as list of values, data sources etc.
  • Add/Update/Delete Resources - The REST API can be used to add/modify/delete resources such as data sources, input controls, queries, file resources etc. in the server repository.
  • Add custom user profile attributes - The REST API can be used to insert custom user profile attributes. This enhancement eliminates the error-prone and cumbersome process of writing and running SQL scripts to insert those attributes into the server repository database.

Jaspersoft has plans to further enhance the REST APIs over the subsequent releases to add support for performing more server operations using REST APIs.

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 "src\main\java\com\jaspersoft\jasperserver\rest\sample\Consts.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".

 

Feedback
randomness