Consume an API in Java

Getting started

Every API can be consumed with a Java client library, that is a wrapper around the JSON API.
The Java client library is always made of two parts:

  • A mashapeClient.jar file to include in your project, that contains the core functionalities of every Java client library and that is immutable for every API.
  • An auto-generated *.java file targeted for the specific API, that has "nearly" the same name of the API.

The client library automatically constructs the "X-Mashape-Authorization" header for every request, and deserializes the response into ready to use Java objects.

Dependencies

In order to use our client library you have to put in your classpath two external libraries (listed in the pom.xml)

Initialize the library

To use the client library, include the auto-generated *.java file (located in the root directory) in your code. Then, initialize a new Java client object, whose class is defined in the auto-generated *.java file and has the same name of the *.java file. The constructor accepts two arguments, that are your Public and Private keys.

For example, if you download the Bitly API's Java client library, you will get the following files:

|- mashapeClient.jar - The base Java client library.
|- Bitly.java - The auto-generated Java source file for the API, that declares a Bitly class.
|- sample.java a sample skeleton to create an instance of Bitly class
|- LICENSE
|- README

To initialize the client library instantiate a new Bitly object setting your Public and Private keys in the constructor. For example take a look at the provided sample.java file:

Call a method

The client object exposes all the methods available for the API, that you can easily call. The methods may require some arguments (some of them may be optional), according to the API's documentation.

The execution of a method may throw a MashapeClientException when a fatal error occurs and the request failed (for example when the keys are not valid). A fatal error is different from a generic error, it means that the HTTP request wasn't successful for the following reasons:

  • You have provided invalid credential keys.
  • No or invalid response by the API.

You can handle the exception with its code and message value, go to the errors section for more info.

For example, a sample client implementation for the Bitly API could be:

Read the response

Every method returns an object that wraps the JSON response that has the same structure like described in the API's documentation.

Handle the response according to the component's documentation. Remember that the response is an object.

Navigate through the response object:

The Java client library internally uses the Java JSON library to deserialize a JSON response into ready to use objects.

Basically what you should know is how the JSON data can be read in Java:

  • Get a String value -> JSONObject.getString("key")
  • Get an Integer value -> JSONObject.getInt("key")
  • Get an Long value -> JSONObject.getLong("key")
  • Get an Boolean value -> JSONObject.getBoolean("key")
  • Get an Double value -> JSONObject.getDouble("key")
  • Get a JSON object value -> JSONObject.getJSONObject("key")
  • Get a JSON array value -> JSONObject.getJSONArray("key")

Here you can find the javadoc for the JSON library: http://www.json.org/javadoc/

Asynchronous requests

The library natively supports asynchronous requests to the API. This is extremely useful when you don't want to wait for a response and continue the execution of your program without interfering.
To call an API's method asynchronously just pass an optional callback parameter object that implements the MashapeCallback interface. The method, instead of returning the API response returns a Thread object. For example:

The MashapeCallback interface has two methods:

  • requestCompleted - Executed when the request is completed. It has an Object response argument, that is the response of the API call. It may be a JSONObject or JSONArray object (depending if the method returns an array or not) according to the documentation.
  • errorOccurred - Executed when an error occurred. It has a MashapeClientException argument, that is the exception raised.

The result can also be null if an error occurred before the Thread is started, for example when the Developer Key is wrong.

Errors

Like the JSON API, there may be API's custom errors or Mashape errors. See the errors section for more info.

Update the client library

It may happen we release a new version of the client library. It's a good practice to update your API's client library installations when a new version is available.

To update the library, delete the mashapeClient.jar file and replace it with the new one. Your implementation should keep working as usual.

If you are consuming more than one API with the client library, a tip could be to keep just one installation of the library (one mashapeClient.jar reference) and move only the auto-generated *.java file for the new components you want to consume into the existing installation. In this way when you will have to update the client library to a newer version, replacing just one jar file is all that's required.