Overview
You may come across many scenarios where it is required to build an API, not just an API, RESTful API powered by suitable technology to empower the customer to access pdf reports over the web.
A report can be anything ranging from salary slip to an equity research document. Allowing customer to download as PDF report has its advantages compared to just showing it in HTML or JSON or XML format.
Java as the backend technology
In this blog, I have chosen Java as the preferred programming language to design and build RESTful web API.
iText library
iText is an open source library for creating and manipulating PDF documents in Java and .Net. This blog uses iText5 version. Please do read about how to create basic PDF documents using the iText library. There are many examples in the iText site to understand it. In this blog, I am trying to focus on how to expose PDF document as the downloadable entity.
Let's get into details on conceptualize, design and build RESTful API.
Pre Requisites
In this blog, I am going to build a Maven based Java project which makes it easy to add and manage dependent libraries automatically.
I assume that you have reasonable experience or theoretical understanding on how to create a Maven Java-based RESTful web project.
You could read more about how to create a Maven based web project here.
iText library as Maven dependency
A brief understanding of using iText API
In iText, PDF is represented under the name Document.
First, you need to create a Document class object. you could do some of the things pointed out below.
First, you need to create a Document class object. you could do some of the things pointed out below.
- Document instance takes page size as the parameter. For example, you could ask the document object to be of the size A4.
- Document title as you need.
- Document instance needs a reference to file or in-memory buffer where contents can be flushed/written.
- Before you could write anything to the document, you need to open it via open() API call.
I have shown below one way to create a document instance, map byte buffer, define page size, open and close it.
You can create some of the complex PDF documents you can think of using the iText library.
How to make the PDF document instance downloadable?
In this blog, I am going to use Java open source RESTful web services library called Jersey to build reports web service.
The below code snippet sums up one of the ways to stream PDF document via Java-based Web API.
There are lots of things going on in the above code snippet. It introduces you to many concepts in Java.
Things to observe/note
- It uses JAX-RS Java annotations. For example, @POST annotation says reports API is accessible as HTTP POST call. @Produces annotation is used to indicate that this reports API generates PDF as API response. Now, Java annotations are very critical Java concept which adds metadata about existing code. Read about Java annotations here and Jersey/JAX-RS annotations here.
- Method getStreamingOutput() makes use of Java8 lambda/functional features.
- As I mentioned earlier, I have created an instance of ByteArrayOutputStream and passed on that instance to PDFWriter. Any content return to Document instance would be available as stream data which can be sent to the calling client as stream-based downloadable content.
Comments