Mapping REST API to Plain Java Objects (POJOs)

Sometimes you want to connect to a REST API from a Java application. There are several approaches to it, from parsing raw JSON content to model the classes in Java with all possible details. In this post, I describe how to solve this in a practical manner, especially the fact of not having the JSON schema for the data that you’re retrieving from the REST API. How can we map this structure to Java Objects with almost no effort? 

I use as an example the SonarQube API, given that is the one employed in another post on this blog.

• A sample REST API: SonarQube
• The problem
• Looking for solutions
• The only [good] solution I have found

A sample REST API: SonarQube

SonarQube is an open source platform to manage code quality. Now they have a cloud version so you can have a look at how it works (API included): sonarcloud.io.

The SonarQube team provides a really good documentation of their API once you deployed Sonar, check for example the cloud version.

The API works with JSON format. You can play a little bit with it by executing, for example, a request for the first three projects:

http https://sonarcloud.io/api/components/search_projects?ps=3

Note: I’m using HTTPie to run this commands from the command line. Alternatively, you can also use Postman, curl or any other tool available.

The problem

Let’s focus on the JSON part (but you could face the same situation using XML). When we get the response below, what should we do with it?

{
    "components": [
        {
            "id": "cca148a5-6722-4114-904a-ba4ec166c7fd",
            "key": "com.adobe:as3corelib",
            "name": "\"AS3 Core Lib\"",
            "organization": "default",
            "tags": [],
            "visibility": "public"
        },
        {
            "id": "AVir1j-5IidNYr2d5L4c",
            "key": "com.hp.ule.struts2project",
            "name": "\"Disenio y programacion seguras\"",
            "organization": "default",
            "tags": [],
            "visibility": "public"
        },
        {
            "id": "AV7CTiZDAFLlVksVgqkT",
            "key": "jpl:develop",
            "name": "\"Jenkins Pipeline Library\" develop",
            "organization": "pedroamador-github",
            "tags": [],
            "visibility": "public"
        }
    ],
    "facets": [],
    "paging": {
        "pageIndex": 1,
        "pageSize": 3,
        "total": 9285
    }
}

One of the options is using the Jackson library and any of the available methods to parse this document:

• Streaming API. Basically, traverse the JSON String as a stream, so we can be fast in finding what we need. This is tedious but, on the other hand, a fast way to cherrypick content.
• Tree Model. Let Jackson parse the JSON for us and then we can traverse it by giving a path. This also requires a lot of code when you need a big part of the information.
• Data Binding (Simple or Complex). We can map the JSON file to Java classes. This can be done the simple way (maps with key-values for example) or the complex way, if we use typed fields and nested classes.

Complex Data Binding is the most natural way of working with JSON data in Java. In our case, imagine that you want to build a table with several properties of the projects in SonarQube and you want to play a little bit with this model (sort, aggregate, etc.). Therefore, we will go for POJOfying the JSON.

Looking for solutions

What would you do next in order to build the POJOs in Java? If you are not a fan of Google you may code the POJO yourself. Actually it’s not as bad for this example, since the JSON is pretty flat. A piece of cake. But you should prepare yourself a coffee if you want to work with the response given by this API when you ask for issues (violations).

You can also try to look for a “POJO Library or JAVA API” from SonarQube. There used to be a Web Service Java Client but that’s not the case anymore. It’s not a common practice to provide the specific language POJOs for a REST API these days. It makes sense: who is going to provide and maintain them?

Then I tried to find the schema, in my opinion, that would be perfect (a Swagger file, for instance, or the JSON schema or metadata). Just like JAXB can generate POJOs given an XSD file, your job would be easy if you have an equivalent solution for a REST API. But, in my experience, is not common that the platforms offer this (looked also for JIRA REST API schema, and didn’t find it).

The only [good] solution I have found

In order to take a good example to play with this solution let’s retrieve the issues from SonarCloud (limiting the page size to 10). My recommendation is that you save the response in a text file.

http https://sonarcloud.io/api/issues/search?organizations=thepracticaldeveloper&ps=10 > issues.json

And the magic comes now. Go to one of the online POJO generators available on the Internet. My favorite is www.jsonschema2pojo.org. Even though the site name could make you think that you need a schema actually you don’t. It infers the data model from the document.

Converting JSON to Java objects

You can either preview the classes that are going to be generated or you can download them directly and include this jar into your project. Ready to go!

If you don’t like the automagically generated POJOs you can always edit them and fine-tune the different fields. It’s a very easy way to be able to do Complex Data Binding with JSON but it still has some cons:

• You may need to do different queries to different services if you want a complete POJO set.
• Some data types can't be inferred, but it is good enough to work with Strings and simple types.
• The dataset you need for feeding the generator has to be significant. If there are some fields missing for the JSON you're using they are not going to be generated in the POJOs, but later they will appear as additional properties.

I hope you find this post useful! Please use the comments box if you want to give feedback or have any question.