AT&T M2X Erlang Client

AT&T M2X is a cloud-based fully managed time-series data storage service for network connected machine-to-machine (M2M) devices and the Internet of Things (IoT).

The AT&T M2X API provides all the needed operations and methods to connect your devices to AT&T's M2X service. This client provides an easy to use interface for Erlang.

Refer to the Glossary of Terms to understand the nomenclature used throughout this documentation.

Getting Started

1. Signup for an M2X Account.
2. Obtain your Master Key from the Master Keys tab of your Account Settings screen.
3. Create your first Device and copy its Device ID.
4. Review the M2X API Documentation.

Getting an Interactive M2X-Erlang Shell

To get an interactive shell, you'll need to install the Erlang/OTP virtual machine and the Rebar build system and dependency manager, either through your system's package manager or by building from the source.

You'll also need to clone this repository using Git.

git clone https://github.com/attm2x/m2x-erlang.git
cd m2x-erlang

From the repository directory, use rebar to fetch dependencies and compile the library.

rebar get-deps && rebar compile

Once the library and its dependencies are built, you can use rebar to get an interactive shell and follow along with the usage examples.

rebar shell

Usage

In order to communicate with the M2X API, you first need to create a client function containing your API key.

> Client = m2x:client(<<"YOUR-API-KEY">>).
#Fun<m2x_client.0.118548121>

You can then use the Client function to call API endpoints directly, as in the following example. The client function accepts a single tuple argument, containing the HTTP method as an atom (get/put/post/delete) and the endpoint as a binary. The result is returned as a tuple containing the status as an atom (ok/client_error/server_error), the status as an integer HTTP status code, and the response body decoded from JSON into a list.

> Client({get, <<"/status">>}).
{ok,200,[{<<"api">>,<<"OK">>},{<<"triggers">>,<<"OK">>}]}

You can also add parameters to be sent in the request body as JSON encoded from an erlang list by adding them as a third element of the tuple passed to the client function. See the documentation for the jsx library for more information about the mapping between JSON types and erlang types.

> Params = [{<<"foo">>,<<"Foo value">>},{<<"bar">>,<<"Bar value">>}],
> Client({put, <<"/no/such/endpoint">>, Params}).
{client_error,404,
              [{<<"message">>,
                <<"The specified resource does not exist">>}]}

To avoid using API endpoints directly, the Client function can instead be passed as the first argument to one of the many convenience wrappers provided by this library. Follow the links to the documentation for the following modules to see all of the available wrapper functions with links to the relevant API documentation.

• m2x - Module documentation - Module source - Web API documentation
• m2x_key - Module documentation - Module source - Web API documentation
• m2x_device - Module documentation - Module source - Web API documentation
• m2x_stream - Module documentation - Module source - Web API documentation
• m2x_command - Module documentation - Module source - Web API documentation
• m2x_device_command - Module documentation - Module source - Web API documentation
• m2x_distribution - Module documentation - Module source - Web API documentation
• m2x_distribution_stream - Module documentation - Module source - Web API documentation
• m2x_collection - Module documentation - Module source - Web API documentation
• m2x_job - Module documentation - Module source - Web API documentation

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. As a summary, given a version number MAJOR.MINOR.PATCH:

1. MAJOR will increment when backwards-incompatible changes are introduced to the client.
2. MINOR will increment when backwards-compatible functionality is added.
3. PATCH will increment with backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Note: the client version does not necessarily reflect the version used in the AT&T M2X API.

License

This library is provided under the MIT license. See LICENSE for applicable terms.