M2X API Documentation

Need help getting started?

Introduction

M2X's RESTful API streamlines the connection between devices and the M2X service, allowing you to build applications and services that leverage time-series data analytics and distributed, high-availability time-series data storage, to deliver meaningful information to your customers and end-users and build IOT and M2M solutions without managing your own storage infrastructure.

The M2X service offers data storage and device provisioning services which are accessed via the M2X API. The cloud-based tools provided by M2X allow you to manage your devices and notifications all from one central location, the M2X Developer Portal.

You can also integrate M2X with other AT&T APIs including Advertising, In-App Messaging, SMS, MMS, Speech, U-Verse, and more.

How M2X Works

At its core, M2X is a cloud-based time-series data storage service that facilitates data transfer and analysis of data from connected devices, applications and services (what we call "Devices" in M2X).

M2X How it Works Diagram

The Developer Portal

Using our developer toolset you'll find that the process of adding new devices to M2X is seamless, simple, and quick.

M2X Summary Diagram

A device can also act as a template, where you can assign device attributes like streams, triggers, location information, and metadata. A device template has the same features as an ordinary device, but a device template is used to define and test device attributes before launch.

You can use any device as a template for creating a new device Distribution. Device Distributions represent a group of devices that retain the attributes of the original device you created.

From the Distributions screen, you can add new distributions and view distribution details like number of devices, registration status, and visibility settings.

Master keys can be used to manage devices, distributions and API keys. You can add and regenerate Master Keys from the Master Keys tab in the Account Settings section. Learn more about API Keys.

Schema

All API access is over HTTPS (although HTTP is supported for devices that cannot connect over HTTPS), and all resources are accessed using the following base endpoint: https://api-m2x.att.com/v2

You can also connect over MQTT if desired using the following endpoint: mqtt://api-m2x.att.com

By default, all data is received as JSON, while supported formats include JSON and MessagePack. Request format can be specified by passing a Content-Type header, while response format can be specified by Accept header. CSV is also supported in some endpoints.

Timestamps

All timestamps are received and returned in ISO 8601 format, with 3 decimal fractions of a second. Timestamps can be sent using any valid timezone, but are converted, stored, and returned as UTC:

YYYY-MM-DDTHH:MM:SS.nnnZ
YYYY-MM-DDTHH:MM:SS.nnn+00:00

Parameters

Most parameters used to identify a specific resource are passed as part of the URL:

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature" -H "X-M2X-KEY: <API_KEY>"

In the example above, both the Device ID (e5e13be8507752e3487f62ab97da6965) and the name of one of its Device Streams (temperature) were specified in the URL.

For GET requests, any parameters not included as part of the URL can be passed as an HTTP query string parameter:

$ curl -i "http://api-m2x.att.com/v2/devices?q=arduino" -H "X-M2X-KEY: <API_KEY>"

For POST, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json:

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature/values" -d "{ \"values\": [{ \"value\": 30, \"timestamp\": \"2014-07-16T02:55:12.345Z\" }] }" -H "Content-Type: application/json" -H "X-M2X-KEY: <API_KEY>"

You can also encode parameters in MessagePack format with a Content-Type of application/x-msgpack:

NOTE: Only UTF-8 encoded parameters are considered valid.

Responses

By default, the response from GET, POST, PUT or DELETE requests will be in JSON format.

You can use Accept parameter to specify MessagePack format:

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature" -H "X-M2X-KEY: <API_KEY>" -H "Accept: application/x-msgpack"

You can also use Accept to manually specify JSON format:

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature" -H "X-M2X-KEY: <API_KEY>" -H "Accept: application/json"

Rate Limiting

M2X limits the number of requests per second a user or device can make. When the limit of any of the rules below is exceeded, M2X returns a 429 Too Many Requests error.

Rules

  • Unauthenticated requests are limited per IP address at 30 requests per second.
  • Authenticated requests are limited per API key at 50 requests per second.
  • Requests that alter (via POST, PUT or DELETE) any resources nested into /v2/devices/:id will be limited per Device id at 10 requests per second. For example, sending PUT /v2/devices/device-123/streams/foo/value and POST /v2/devices/device-123/update inside the same 1 second window will count both requests as hits for the Device with id device-123. If the /v2/devices/serial/:serial_id routes are used the hits will count for the serial_id instead of the Device id.

Response

M2X API will include the following headers in all requests:

  • X-RateLimit-Limit: The limit of requests for the current window of time (one second). It depends on the rule enforced on the request.
    • 30 when the request is unauthenticated.
    • 50 when the request is authenticated.
    • 10 when the request is authenticated and to an endpoint used to create, modify or delete a device, stream, datapoint or waypoint.
  • X-RateLimit-Remaining: The number of requests still available inside the current window.
  • X-RateLimit-Reset: The Unix UTC time in seconds since Epoch of when the next window will open, i.e., the following second.

When the limit of requests is reached, M2X returns a 429 Too Many Requests response with the Retry-After header. The body of the response is a JSON document with the following schema: {"message": "<reason for the 429 error>"}.

API Error Codes

M2X uses standard HTTP status codes to indicate success or failure of an API request.

HTTP Status Code Summary

200 OK - Request has succeeded.

201 Created - Request has been fulfilled and a new resource created.

202 Accepted - The request has been accepted for processing, but the processing will be completed asynchronously

204 No Content - The server has fulfilled the request but does not need to return an entity-body.

400 Bad Request - Bad request (e.g. sending an array when the API is expecting a hash.)

401 Unauthorized - No valid API key provided.

403 Forbidden - You tried to access a disabled device, or your API key is not allowed to access that resource, etc.

404 Not Found - The requested item could not be found.

405 Method Not Allowed - The HTTP method specified is not allowed.

415 Unsupported Media Type - The requested media type is currently not supported.

422 Unprocessable Entity - Can result from sending invalid fields.

429 Too Many Requests - The user has sent too many requests in a given period of time.

500, 502, 503, 504 Server errors - Something went wrong in the M2X server.

More information about each specific error is included in the body of each response.

HTTP Verbs

Use the appropriate HTTP verbs for each action:

HEAD

Can be sent against any resource accessible via GET to retrieve only the HTTP headers.

GET

Used for retrieving resources.

POST

Used for creating resources.

PUT

Used for updating resources or collections.

DELETE

Used for deleting resources.

OPTIONS

Used for obtaining more information about which actions can be performed on the specified resource.

Authentication

Unless stated otherwise, all requests sent to the API must be authenticated using one of these two methods:

  • by including a valid M2X API key in the X-M2X-KEY HTTP header.
  • by including a valid M2X API key in the Authorization HTTP header in the format Authorization: Bearer <API_KEY>.

If a valid API key is not provided, the server will respond with with a 401 Unauthorized message. If a valid API key is used to access a resource of a different account the server will respond with a 403 Forbidden.

API Keys

There are several different kinds of API keys in M2X:

  • Master API Keys

    Each time a user signs up for M2X, a Master Key is created and assigned to that new user's account. This key is also known as the primary master key and it can't be edited or deleted. If needed, it can be regenerated (e.g. if there's any risk that someone else has gained access to that key).

    Master Keys can be used to manage devices, distributions and API keys.

    An M2X user can create any number of additional Master Keys, each with its own different set of restrictions, either for his own use or to distribute to other developers or devices.

  • Device API Keys

    Each time a device is created in M2X, a new Device Key is created and associated with the new device that has just been created. This key can't be edited or deleted: it can only be regenerated if needed (e.g. if there's any risk that someone else has gained access to that key).

    Unlike Master Keys, Device Keys can't be used to manage other devices, distributions or API keys. They can only be used to access the metadata, streams, values and location of the device which they are associated with. They can't access data from any other device.

    Additionally, a Device Key's access can be limited to a single stream of the associated device.

    An M2X user can create any number of additional Device Keys, each with its own different set of restrictions, either for his own use or to distribute to other developers or devices. For example, you could create one API key that can only be used to push values to the temperature stream, another API key to push values to the humidity stream, and a third API key that can be used to read the values from both streams.

  • Collection Keys

    Just as with devices, newly created collections will also have a primary key associated with them. In this case, however, it will be a Collection Key, which grants the same permissions and has the same restrictions as Device Keys, except that Collection Keys can be used for any device inside the collection, or any of its sub-collections.

    It's important to note that moving or adding sub-collections will directly affect which devices the parent Collection Key can access, so developers need to keep that in mind when editing collections and sharing their keys with other users.

  • Distribution Keys

    As with devices and collections, newly created distributions will have a primary key associated with them. In this case it will be a Distribution Key, which grants the same permissions and has the same restrictions as Device Keys, except that Distribution Keys can be used for any device created within the distribution. This type of key can only be used to access devices, not to modify the associated distribution itself. Modifying a distribution requires a Master Key.

All types of keys can be used in the X-M2X-KEY header to authenticate requests sent to the M2X API, the only difference remains in the operations that each key is allowed to perform.

API Keys can have different restrictions:

  • API key type: with the exception of accessing devices and streams, all other API endpoints require a Master Key. Listing or searching devices also requires a Master Key.
  • HTTP Method: a developer can define which HTTP methods (GET, POST, PUT and DELETE) can be used with each API key. HEAD requests can be used whenever a GET request is allowed. OPTIONS can always be used, although the response would depend on the API key used (it will only return those methods which are accessible by the same key.)
  • Expiration: an API key can have an expiration date. If the API key has expired the server will respond with a 403 Forbidden response and a Your API key has expired message.
  • Origin: a developer can specify a list of IP addresses that are allowed to use this key.
  • Device API Key: an API key that has been restricted to a device or stream will only have access to that resource. All other cases will return an error response.

JSON-P Callbacks

You can send a callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed M2X content in web pages and get around cross domain issues.

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature?callback=foo" -H "X-M2X-KEY: <API_KEY>"

Then you can write a JavaScript function that will process the data received from the server:

function foo(data) {
  console.log(data);
}

Pretty JSON

By default, whitespace in JSON responses is compressed. You can easily change this behavior and start receiving more readable JSON responses by passing a pretty parameter to any request.

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature?pretty" -H "X-M2X-KEY: <API_KEY>"
$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature?pretty=true" -H "X-M2X-KEY: <API_KEY>"

Both options displayed above can be used to enable pretty JSON responses. For your convenience, you can also return the whitespace-compressed response by setting the pretty parameter to false:

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature?pretty=false" -H "X-M2X-KEY: <API_KEY>"

Setting the pretty parameter to false is equivalent to not specifying it at all, such as:

$ curl -i "http://api-m2x.att.com/v2/devices/e5e13be8507752e3487f62ab97da6965/streams/temperature" -H "X-M2X-KEY: <API_KEY>"

Resources

Following is a short list of useful terms that describe the core functionality of M2X:

Devices

A Device is any individual generator of data that can be connected to M2X. This could be a physical device, application, service, or something else (e.g. a smart thermostat, iPhone app, etc.). Learn more about Devices.

Device Templates

Device Templates are considered prototype Devices and are used to define and test Device attributes like streams, triggers, location information, and metadata, before launch. Launching a Device Template forms a Distribution. Notice that any Device can acts as a Device Template.

Collections

Collections allow Devices to be grouped together in a folder-like structure. Collections can be nested within other collections. Learn more about Collections.

Distribution

Distributions represent a group of Devices that begin life with the attributes of the original device template when created. Learn more about Distributions.

Streams

A Stream is a sequence of timestamped values for a single source of measurement data. For example, a thermostat measuring temperature will have a single data Stream. Another thermostat that measures temperature, humidity and atmospheric pressure will have three different Streams.

Each Stream is identified by name, which should be unique within a given Device. There are two supported stream types, numeric and alphanumeric.

Streams can be interacted with via the Device and/or Distribution APIs.

Values

Values are individual measurable data points and are Device dependent (i.e. a thermometer will only create temperature values). These data points make up a Stream.

Values pushed to Streams of type numeric are limited by precision and are stored as 64-bit floating point numbers. Values pushed to Streams of type alphanumeric are limited to a maximum of 5,000 characters.

Triggers

Triggers are used to create notifications that alert you when a specific event occurs (e.g. a change in temperature or a drop in volume). Triggers are defined at the Device or Distribution level and support conditions based on one or more Streams. Learn more about Triggers or review the Triggers Tutorial.

For a full list of terms and definitions view the M2X Glossary

APIs

The M2X API can be divided into a number of different groups:

MQTT

In addition to HTTP, M2X also supports the MQTT protocol. Review the MQTT documentation for more details.

Security

M2X supports the following protocols:

  • TLS 1.2
  • TLS 1.1
  • TLS 1.0

To view a listing of active Cipher Suites run the following command in your Terminal (requires nmap):

nmap --script ssl-enum-ciphers -p 443 m2x.att.com