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
- Signup for an M2X Account.
- Obtain your Master Key from the Master Keys tab of your Account Settings screen.
- Create your first Device and copy its Device ID.
- 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
:
-
MAJOR
will increment when backwards-incompatible changes are introduced to the client. -
MINOR
will increment when backwards-compatible functionality is added. -
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.