How to Use Mashape’s Auto-Generated Java client library for your Android apps

UPDATE (Dec 10, 2013):  The instructions below are outdated.  Please head to this post on how to call Mashape APIs in your Android projects.

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.

Auto-generated client libraries

Auto-generated client libraries

This saves both the API provider and consumer / developer a huge amount of coding time and manpower, which allows them to 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:

  1. 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.
  2. Depending on the Android platform you’re targeting, 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.

Auto generated Java client library

Java/Android auto-generated client library

When you extract the contents, you will get the following files:

Mashape Java Client

Mashape Java Client

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.  

Project view in Eclipse

Project view in Eclipse

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.

Dialogue window

Dialogue window

 

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.

Project view after importing required jar files

Project view after importing required jar files

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.

Mashape Sample Android App

Mashape Sample Android App

From the UI above you can see that we’re letting the user type in a question in the edit text 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:

    
    public void sendMessage(View view) {
        
    	EditText editText = (EditText) findViewById(R.id.edit_message);
    	String message = editText.getText().toString();
    
    	new CallMashapeAsync().execute(message);
    	
    }
    
    private class CallMashapeAsync extends AsyncTask<String, Integer, MashapeResponse<JSONObject>> {
    
    	protected MashapeResponse<JSONObject> doInBackground(String... msg) {
    		
    		QuestionAnswering client = new QuestionAnswering("MASHAPE_KEY");
    		return client.answerAQuestion(msg[0]);
    	}
    	
    	protected void onProgressUpdate(Integer...integers) {
    	}
    	
    	protected void onPostExecute(MashapeResponse<JSONObject> response) {
    		String answer = response.getBody().toString();
        	TextView txtView = (TextView) findViewById(R.id.textView1);
        	txtView.setText(answer);
    	}
 
    }
    

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.

Android App with Question-Answering API on Mashape in action

Android App with Question-Answering API on Mashape 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 support@mashape.com or check us out in Facebook http://www.facebook.com/mashape