UPDATE (Oct 28, 2013): The steps below are already outdated because Mashape now generates the Unirest code snippets (instead of the library indicated in the steps below). In the case below, you would import the Unirest Java library.
One of the ways that Mashape facilitates easy consumption of APIs is by offering auto-generated client libraries for several programming languages, for each of the APIs. You can see these as a row of buttons lined up in the middle-right section of each API page in Mashape.
This saves both the API provider and consumer / developer a huge amount of coding time and manpower, which lets them attend to more important things like running their core business, or brainstorming on code logic for new product features.
This post will guide you on how to use Mashape’s auto-generated Java client library to consume Mashape APIs in your Android apps. A sample code is also provided at the end of this post so you can review and test.
There are generally two things to remember when consuming Mashape APIs in your Java Android application:
- The Mashape client library might require you to import class libraries that are not in your Android project, depending on the Android platform and API level you’re targetting. These will usually manifest itself as a runtime exception. The IDE debugger and Github are your best friends in these cases.
- Depending on the Android platform you’re targetting, you may or may not be required to wrap the client call in an asynchronous class. The latter is usually the the case for newer Android platforms. The sample code provided here uses an asynchronous call.
Ok let’s get started!
In this example, we will use Webknox’ Question-Answering API to create an Android app that lets the user get answers to user-typed questions. (NOTE: You have to be subscribed to a plan to consume the Question-Answering API). The tutorial below however will assume that you have already created your default Android project in the Eclipse IDE, and will only focus on the Mashape integration part.
1. Download the Java/Android auto-generated client library for the Question-Answering API.
When you extract the contents, you will get the following files:
Generally, you will only need to import the mashape-java-client-*.jar and the QuestionAnswering.java into your project. These two files respectively contain the Mashape and QuestionAnswering classes and functions to make the API call and get a response.
2. Import the Mashape client library files into your project.
The image above is my project view in Eclipse, showing where I imported the two files from number 1 to. QuestionAnswering.java goes to the “src” folder, and the Mashape java client jar file goes to the “libs” folder. This is of course a matter of preference, as long as the files are accessible from your build path.
You need to “include” the QuestionAnswering.java, and change the package name at the top to whatever your project is using.
Adding a jar file to the “libs” folder (in my case in Eclipse), automatically adds it to the “Android dependencies” (see image above). In others you might have to manually add to the build path by right-clicking the main project and navigating to Build Path->Configure Build Path. This opens up the dialog window (in the image below) where you can start adding jar files and what not, into the build path.
3. Download and import the other jar files below:
- Apache HttpClient - download, extract, and find the httpmime jar inside. Import it to your project in the “libs” folder.
- Gson - extract and import to your project in the “libs” folder.
These are required by the Mashape client library. If you already have these imported, then you don’t have to do this step.
This is how it looks like after importing.
At this point, we’re all set and we can start calling the library functions to make a call to the Mashape API endpoints.
But let’s explore first what the UI looks like, so we can understand the sequence of events before we actually call the API.
From the UI above you can see that we’re letting the user type in a question in the edittext field. The Send button will then pass the question and call our Mashape API Question-Answering, and return a response which will be shown in the Results textview.
4. Call the Mashape client library
The code that gets called for the Send button looks like below:
The “sendMessage” gets called when the Send button is clicked. We then wrap the calling function in an AsyncTask (“CallMashapeAsync”) to avoid the use of threads and handlers. This keeps the UI happy while the library retrieves the API response.
Note that you also have to plug in your Mashape public and private keys.
Here’s the sample app in action.
To wrap up - Mashape lets you access the APIs faster with the auto-generated client libraries. This example showed you how we can use the auto-generated Java client library to call Mashape APIs in Android.
As always, we welcome your feedback! Please email us at firstname.lastname@example.org or check us out in Facebook http://www.facebook.com/mashape