(This article was first published on LinkedIn.)

When developing applications, you’ve probably faced a situation in which you need to integrate with third-party APIs, either to improve a service that provides users with data or to add a new functionality. Many software engineers solve this by mapping complex DTOs, but there's a much easier method available. 

The traditional method for integrating third-party APIs with any given application is as follows: 

• 1. Read the API documentation.

• 2. Find the endpoint(s) you need to call.

• 3. Determine which data you need to use from this API.

• 4. Use DTOs to map all of the data that the API returns.

What many software engineers don't realize is that this process is unnecessarily time consuming, which compromises the overall business value of the development project. On the other hand, using Java EE JsonObject and JsonPointer is much more time effective. Let's compare the two approaches with the following example.

Adding a New Feature to the App

Imagine that you work for a company whose main app recommends beverages to clients.  (I've created a simple application to mimic this app; you can download the source code here.)

As you can see, the app simply suggests beverages randomly to clients when they make calls to this URL. The following options are available: "Coffee," "Beer," "Hot Chocolate," "Smoothie," and "Tea."

So far, our app is a huge success (after all, who wouldn’t want an app that randomly recommends beverages?), but the marketing team thinks the app's advertising would be more effective if beverage suggestions were made based on current temperatures in each user's general location. 

To add this new feature to the app, we decide to use this weather API. If you take a look at the documentation of this API, you will see that it returns the current temperature (and ancillary data) based on the location selected. Here is an example:

By analyzing this data, we discover that we only need the field “temp” that is inside the “main” JSON object. With this knowledge in hand, we can proceed to integrate the third-party API with our main app. 

Common Methodology

Based on the JSON above, your solution may be to map all the data with some Java classes, make the API call, and marshal the response into your classes so that you can pick the current temperature from the info. This methodology is depicted in the diagram below:

This diagram perfectly illustrates how some "simple" mapping can turn into a somewhat complex class hierarchy full of terms whose meanings we don't know and that don't have any bearing on our purpose (the beverage app). We simply want to know the current temperatures and correlate them to different drinks, but instead we've increased the complexity of our domain and consumed valuable time trying to understand and map several terms into our system. 

At this point, you may be wondering how to access the information you need without mapping the whole object graph. Java EE and the JSON-P API (JSR 374) answer this question in the form of JsonObject and JsonPointer.

A Smarter Methodology

First, we will create a new class called TemperatureService inside our control package (if you are wondering why I chose such names for the packages, view this video) with the following code inside it:

The code above calls the weather API and maps its return to a JsonObject (from json-p spec). We can use this to create a JsonPointer to the field we want inside the JSON (something like an XPath for XML). Then we can easily use this pointer to extract the data we need from the JSON without creating any class inside the domain, thereby saving hours of mapping classes to values that don't contribute at all to our app.

You can test the API using the following URLs:

(Beverage suggestions that don’t consider temperature).

(Beverage suggestions that do consider temperature).

Conclusion

At Avenue Code, we love finding and sharing time-saving methodologies for developing quality products, and we're always looking for new ways to learn. So tell us what you think of this approach in the comments below--how do JsonObject and JsonPointer work for you? Do you see advantages we haven't pointed out? Any reasons you'd prefer to continue using DTOs? We look forward to hearing from you!