Documentation Get Support

Consume an API in Erlang

Getting started

Every API can be consumed with an Erlang client library that acts as a wrapper around the REST API.
The Erlang client library is made of two parts:

  • An emashape application, that contains the core functionalities of every Erlang client library and that is immutable for every API.
  • An auto-generated *.erl 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 Erlang data using mochijson2.

Download client library

Download the auto-generated client library for the API you want to consume first.


Our Erlang client library uses ibrowse, mochiweb's JSON module and erlang-uuid for UUID creation.

Initialize the library

The constructor accepts two arguments: your public and private keys.

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

|- deps/ - The base Erlang dependencies.
|- |- ibrowse-2.1.3/
|- |- mochiweb-1.5.0/
|- |- ossp_uuid-1/
|- lib/ - The Erlang client applicatoin.
|- |- emashape-01/
|- bitly.erl - The auto-generated Erlrang source file for the API, that declares a Bitly module.
|- sample.erl a sample skeleton to create an instance of Bitly class

Call a method

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

For optional arguments they are passed as a proplist. Example: [{"opt_arg1", "value"}, {"opt_arg2", "value2"}].

The API methods are called through Erlang functions of the form ApiModule:MethodName(RequiredArgs1, RequiredArg2, ..., OptionalArgsList, Callback)

Read the response

Every method returns a JSON struct that wraps the JSON response and has the same structure described in the API's documentation.

Handle the response according to the component's documentation.

Asynchronous requests

The library natively supports asynchronous requests to the API. This is extremely useful when you want to continue the execution of your program without waiting for the response. 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 or a PID for an Erlang process to send the result to (as a tuple {result, Result})as the last parameter to the method. For example:

Update the client library

It may happen that 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 lib/emashape-* folder and replace it with the new one. Your implementation should keep working as usual.