Jsp Based Rest Api Framework

JAX-RS

Being a java developer, I have always used JAX-RS for building REST APIs. JAX-RS gives you a neat API. There is Apache CXF, but I preferred jersey. Since I could use jersey in my web app along with servlets.

Using JAX-RS was easy. It felt like using servlets with annotations. It had the same mechanism of defining URI for the resource and assigning HTTP Verbs to methods.

The spec did well to address REST API specific requirements like

• setting status code,
• declaring output format.
• Handling parameters with annotations etc.

I have been actively working on an open-source project to build REST APIs with JSP.

JSP for REST APIs

JSP has the same readability advantage as an XML, provided we don't use scriptlets. We can extend JSP with tag libraries and the expression language is very powerful.

JSP is preferred over servlets in a lot of cases. Generating HTML, output, iterating over data can be easily done in JSP. JSP is java's answer to PHP and it is arguably more powerful than PHP.

Taking all the above advantages into consideration, we worked on a project to build REST APIs with JSP. JSP as a REST Resource

The idea is to treat each JSP page as a rest resource. By doing this, we can avoid declaring URLs for our rest resources. Each resource URL is implied.

REST Resource requirements

1. Handle all the HTTP verbs.
2. Provide URI for the resource
3. Produce response
4. Handle errors

A JSP can do all the above and many more things that a rest resource needs.

• Tag Libraries

JSTL provides a good number of tags for formatting, SQL operations, functions, and logical operations. Maintaining a JSP with tag libraries and JSTL is easier than maintaining java code.

Using JSTL to Enhance JSP Functionality

• Custom Tags

JSP custom tag development allows organizing commonly used operations into tags. This helps us to main domain-specific tags and reuse them across the JSP pages.

• Hot Deploy

Writing a quick display page is much easier and changes get hot deployed using JSP just like PHP. JSP works like a scripting language (save and run).

JSTL SQL Tags

As per this SO question How to use JSTL SQL tag, you can see in the answer that it is suggested not to use SQL in JSP pages.

The reason you don’t use JSP for SQL is that it is coupled with table display logic or HTML generation. For which they mentioned, it’s good for small use.

If JSP has all tags which are essentially java code running, we have zero HTML code in the JSP. So it behaves just like a servlet. I think a servlet will perform better slightly, but won’t be as productive and easy to use as JSP.

Coming to using a bean, they use beans since they use MVC to do all the logic and JSON conversion. We do all that internally and have cogs and wheels to do them internally.

SQL Tag Library

The DAO Pattern

Data access layer and service layer is separated to reuse the database operations. Multiple service operation may need to use the same set of queries. Also keeping database operations in DAO helps to decouple business logic from database operations.

Keeping this in mind, the mason project allows developers to maintain queries in a separate file. So they can be referenced by multiple JSP resources.

Advantages of storing SQL in a properties file.

1. SQL can be changed without application rebuild
2. Decouples the SQL logic from the application business logic
3. A central repository of all SQL statements – easier to maintain
4. Easier to understand

There is a long discusson this topic on stackoverflow

REST Tags

As you can see in the below image a GET request is mapped to an SQL query.

<jsp:directive.include file="../fragments/mason-init.jspf"/>
<%-- customer.jsp --%>
<m:resource>
    <m:request method="GET">
        <sql:query var="result" dataSource="${datasource}">
        SELECT name, address, phone, type from retail_customer
        </sql:query>
        <c:set target="${masonOutput}" property="all customers" value="${result}"/>
    </m:request>
</m:resource>

Building domain-specific tags like resource , request, param etc. help to make the JSP resource easy to declare a rest resource. These tags are more readable than JAX-RS methods and annotation.

As these rest tags are domain-specific they

• handle request parameters
• handle client errors and generate error response
• collect SQL and code results
• generate XML/JSON response

You can find more resource examples in mason sample project.

Use Cases

1. Expose API over the database
2. Prototype for a complex REST API
3. Microservice
4. API gateway to a web application over the database

Github Repo

Mason is an open source project licensed under LGPL. And you can try out the sample webapp.