Consume an API in JSON

Getting started

Every API listed on Mashape can be consumed via a RESTful JSON API, where all the responses are JSON objects. You can consume an API manually, as illustrated below, or using a client library.

Consuming manually an API involves two steps:

  • Create an authorization hash using your private and public keys and a UUID (Universally unique identifier, an unique string value that always changes between different requests: it can be a timestamp value for example).
  • Consume the API by properly setting an X-Mashape-Authorization HTTP header with the Base64 representation of the Authorization Hash.

Note that the client libraries create and set the authorization header automatically.

Preparing the Authorization Header

Every request require an "X-Mashape-Authorization" header valued like:

So basically you create an hash that is an HMAC-SHA1 signature of an UUID you have previously generated.

The UUID value can be whatever that always changes between different requests with no or low probability that the same UUID can be used more than once. For example a timestamp or a random string.

Put the whole Base64 encoded value and put it in a "X-Mashape-Authorization" header. You have to do this every time you make a request to an API.

Calling an API method

Calling an API method using JSON is easy. Just go the the API's profile and click the JSON button:

json button

A modal pop-up will appear showing you the URL for the HTTP request and the HTTP method (GET, POST, PUT or DELETE) for it:

json modal

Note: the URL may have some highlighted text that represent the parameters to enter. Read the documentation, some of them may be optional.

Reading the response

Each response generated by an API method has the same structure like described in the method's documentation.

Errors

An API request may generate an error, that is returned in the response.

  • Errors are JSON objects described in the Error section of the documentation.

Two types of errors could occur:

  • Errors generated by the Mashape API: for example the API has a bad configuration, or you requested an authorization token providing an invalid Developer Key.
  • Errors generated by the API: errors that are generated by the component's business logic, for example generated by a bad validation over a parameter.

Errors generated by Mashape

An error presents an unique code key containing a numeric code to be read by the machine, and a message key containing an human readable description of the error.

  • 1000 - A generic exception occurred in the library. See the message field for more info.
  • 1001 - Bad XML configuration. See the message field for more info.
  • 1002 - You made a request with a wrong HTTP Method (for example making a GET request while the method you're calling expects a POST request).
  • 1003 - Http Method not supported (DELETE, GET, POST, PUT are supported).
  • 1004 - Operation not supported.
  • 1005 - Can't autorize the request because the server key set in the PHP file is wrong.
  • 1006 - The method requested was not found.
  • 1007 - The request has not been authorized. Require a valid token (it may be expired, require a new token for every request).
  • 1008 - Some required parameters of the method you're calling are missing.
  • 2000 - A generic error. See the message field for more info.
  • 2001 - Invalid Developer Key
  • 2002 - You exceeded your API request limit for the component you've called
  • 2003 - Invalid JSONP Token
  • 2004 - The request was made by an unauthorized domain (JSONP)
  • 2005 - The API requires a subscription
  • 2006 - Your subscription has been temporary suspended

Errors generated by the component

A component method may return specific errors when executed, as stated in the API method description under the "Errors" section: