Consume an API in Python

Getting started

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

• A mashape package, that contains the core functionalities of every Python client library and that is immutable for every API.
• An auto-generated *.py 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 Python objects.

Dependencies

Our python client library uses httplib2

Initialize the library

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

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

|- mashape - The base python client folder.
|- Bitly.py - The auto-generated python source file for the API, that declares a Bitly class.
|- sample.py 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:

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.

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.

Asynchronous requests

The library natively supports asynchronous requests to the API. This is extremely useful when you don't want to wait for the response and continue the execution of your program without interfering. Your code will receive the response from the api execution as a parameter to the provided callback function
To call an API's method asynchronously just pass a callback function as the last parameter to the method. The execution of the method, instead of returning the API response returns a Thread object. For example:

Errors

Like the JSON API, there may be component'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 mashape folder 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 mashape folder) and move only the auto-generated *.py 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 folder is all that's required.