Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
103 lines (75 sloc) 4.03 KB

AT&T M2X Elixir 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 library aims to provide a simple wrapper to interact with the AT&T M2X API for Elixir, a dynamic, functional language designed for building scalable and maintainable applications.

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.

Installation

This library is available on hex.pm. To use it in your project, add m2x to your list of dependencies in mix.exs.

def deps do
  [{:m2x, "~> 2.0"}]
end

Usage

This library uses Elixir structs to contain data fetched from the AT&T M2X service, but these also contain all the data necessary to interact with the resource again, so they are used as convenience handles for deeper levels of the API.

In order to communicate with the M2X API, you need to create an M2X.Client struct containing your API key.

M2X.Client

client = %M2X.Client { api_key: "<YOUR-API-KEY>" }
#=> %M2X.Client { ... }

The M2X.Client struct can be passed to functions that fetch existing remote resources and return their corresponding structs for further interactions:

  • M2X.Device

    {:ok, device} = M2X.Device.fetch(client, "<DEVICE-ID>")
    #=> {:ok, %M2X.Device { ... }}
  • M2X.Distribution

    {:ok, distribution} = M2X.Distribution.fetch(client, "<DISTRIBUTION-ID>")
    #=> {:ok, %M2X.Distribution { ... }}
  • M2X.Collection

    {:ok, collections} = M2X.Collection.fetch(client, "<COLLECTION-ID>")
    #=> {:ok, %M2X.Collection { ... }}
  • M2X.Key

    {:ok, key} = M2X.Key.fetch(client, "<KEY-ID>")
    #=> {:ok, %M2X.Key { ... }}
  • M2X.Job

    {:ok, key} = M2X.Job.fetch(client, "<JOB-ID>")
    #=> {:ok, %M2X.Job { ... }}
  • M2X.Stream

    {:ok, device} = M2X.Device.fetch(client, "<DEVICE-ID>")
    {:ok, stream} = M2X.Device.stream(device, "<STREAM-NAME>")
    #=> {:ok, %M2X.Stream { ... }}

The M2X.Client struct can also be passed to REST methods to directly access any M2X API endpoint and get an M2X.Client.Response struct in return:

M2X.Client.Response

res = M2X.Client.get(client, "/some_path")
#=> {:ok, %M2X.Client.Response { ... }}
res = M2X.Client.post(client, "/some/other_path", %{ "foo"=>"bar" })
#=> {:ok, %M2X.Client.Response { ... }}
res = M2X.Client.get(client, "/some_unknown_path")
#=> {:error, %M2X.Client.Response { ... }}

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.