Integrations API

Integrations are used to forward data between M2X and other services.

Data from all or a subset of devices may be selected to be forwarded by the integration. Only devices owned by the same account which owns the integration may be selected by it.

Each type of integration available has a specific set of configuration fields that may (or must) be applied. These fields will set up aspects of the integration that are specific to the service being integrated with.

Authentication

The Integrations API endpoints require a Master API key in the X-M2X-KEY header. Any attempt to use the incorrect key to access these endpoints would result in a 403 Forbidden response. Learn more about API Keys.

Integration Types

Currently there are two known integration types:

AMQP Sink Integration

An integration of type amqp_sink will direct M2X to forward all incoming datapoints and waypoints from selected devices to a specific queue on an AMQP broker. A user-owned application may connect to the AMQP broker as a client and subscribe to consume the events. User applications should connect with an AMQP-compatible client, such as one of the official RabbitMQ client libraries

Data forwarded from the selected devices will be published as messages to an AMQP queue whose name is randomly generated with a user-specified queue_suffix, as defined in the integration's configuration. The user application is not required to declare the queue before consuming from it, and indeed declaring queues is not allowed, so if the user application does so, it will be met with an authorization error.

Message delivery should be considered reliable, but messages will not be retained indefinitely - if the user application is disconnected for a significant amount of time, or falls behind the rate of incoming messages, messages may be dropped. For highest reliability, it is advised that the user employ redundant consumers, such that consumers are always connected and available to receive and acknowledge messages at a rate at least as high as the rate at which the messages are incoming.

AMQP Sink Connection Information

The info fields of the View Integration Details endpoint will give the necessary information needed for the user application to connect to the AMQP broker and start consuming from the queue. For example, consider the following info fields:

"info": {
  "amqp_url": "amqp://4996618675ef53c780c6b97b18a1d00a:f0bb17bb991bcc9d031b5060dd243d53@amqp-pipelines.m2x.sl.attcompute.com:5672/",
  "queue": "items.4996618675ef53c780c6b97b18a1d00a.my-queue"
}

This would indicate that the user application should connect to the AMQP broker at amqp-pipelines.m2x.sl.attcompute.com on port 5672, authenticating with the username of 4996618675ef53c780c6b97b18a1d00a and a password of f0bb17bb991bcc9d031b5060dd243d53. After connecting and authenticating, the application could begin consuming from the queue named items.4996618675ef53c780c6b97b18a1d00a.my-queue to start receiving messages.

A robust user application should always fetch this connection information from the M2X API when connecting to the AMQP broker, rather than hard-coding the values into the application, as they may be subject to change in the future.

AMQP Sink Examples

With the default configuration, an incoming M2X datapoint on a numeric stream named temperature with a value of 32 would cause a message to be published to the AMQP queue with a JSON payload that looked like this:

{
  "id": "20203f3c2beeb31e72814ffd5200c2fb",
  "timestamp": "2014-09-10T19:15:00.756Z",
  "metadata": { "M2X-DEVICE-ID": "65b89448f954f49e42b746d73b385cbb" },
  "values": {
    "temperature": 32
  }
}

An incoming M2X location waypoint would cause an AMQP message with a JSON payload that looked like this:

{
  "id": "20203f3c2beeb31e72814ffd5200c2fb",
  "timestamp": "2014-09-10T19:15:00.756Z",
  "metadata": { "M2X-DEVICE-ID": "65b89448f954f49e42b746d73b385cbb" },
  "values": {
    "@location": { "latitude": -37.97884, "longitude": -57.54787, "elevation": 5 }
  }
}

When using M2X API endpoints that allow you to push multiple datapoints and/or waypoints with the same timestamp in a single request, all values with the same timestamp would be grouped into the same AMQP message:

{
  "id": "20203f3c2beeb31e72814ffd5200c2fb",
  "timestamp": "2014-09-10T19:15:00.756Z",
  "metadata": { "M2X-DEVICE-ID": "65b89448f954f49e42b746d73b385cbb" },
  "values": {
    "@location": { "latitude": -37.97884, "longitude": -57.54787, "elevation": 5 },
    "temperature": 32,
    "color": "blue"
  }
}

AMQP Sink Configuration

The AMQP queue name used for queueing incoming messages can be influenced using the following configuration field. This field is required.

  • queue_suffix the suffix to be appended to the randomly generated queue name.

HTTP Sink Integration

An integration of type http_sink will direct M2X to forward all incoming datapoints and waypoints from selected devices to a callback URL on a third-party user-owned web server.

If the user-owned web server at the given callback URL responds with an error or is unavailable for connection, the integration will be disabled and need to be re-enabled using the Update Integration Status endpoint.

Message delivery should be considered reliable, but messages will not be retained indefinitely - if the user application is disconnected for a significant amount of time, or falls behind the rate of incoming messages, messages may be dropped. For highest reliability, it is advised that the user employ redundant consumers, such that consumers are always connected and available to receive and acknowledge messages at a rate at least as high as the rate at which the messages are incoming.

HTTP Sink Examples

With the default configuration, an incoming M2X datapoint on a numeric stream named temperature with a value of 32 would cause an HTTP POST request to be sent to the configured callback URL with a JSON payload that looked like this:

{
  "id": "20203f3c2beeb31e72814ffd5200c2fb",
  "timestamp": "2014-09-10T19:15:00.756Z",
  "metadata": { "M2X-DEVICE-ID": "65b89448f954f49e42b746d73b385cbb" },
  "values": {
    "temperature": 32
  }
}

An incoming M2X location waypoint would cause an HTTP request with a JSON payload that looked like this:

{
  "id": "20203f3c2beeb31e72814ffd5200c2fb",
  "timestamp": "2014-09-10T19:15:00.756Z",
  "metadata": { "M2X-DEVICE-ID": "65b89448f954f49e42b746d73b385cbb" },
  "values": {
    "@location": { "latitude": -37.97884, "longitude": -57.54787, "elevation": 5 }
  }
}

When using M2X API endpoints that allow you to push multiple datapoints and/or waypoints with the same timestamp in a single request, all values with the same timestamp would be grouped into the same HTTP request:

{
  "id": "20203f3c2beeb31e72814ffd5200c2fb",
  "timestamp": "2014-09-10T19:15:00.756Z",
  "metadata": { "M2X-DEVICE-ID": "65b89448f954f49e42b746d73b385cbb" },
  "values": {
    "@location": { "latitude": -37.97884, "longitude": -57.54787, "elevation": 5 },
    "temperature": 32,
    "color": "blue"
  }
}

HTTP Sink Configuration

There is only one allowed configuration field, and it is required.

  • callback_url the URL of the HTTP web server that will receive HTTP POST requests.

Pusher Sink Integration

An integration of type pusher_sink will allow M2X to forward all incoming datapoints and waypoints from selected devices to a user-owned Pusher application. The data will then be forwarded by the Pusher service to any connected and subscribed clients using the Pusher client libraries.

Data forwarded from the selected devices will be published as events to a Pusher channel. Datapoint values (from both numeric and alphanumeric streams) will be sent as with datapoint as the event name, to a channel based on the stream name. Location waypoints will be sent with waypoint as the event name to a channel based on the name location. The format of the channel names can be configured in the integration's configuration.

Pusher Sink Examples

With the default configuration, an incoming M2X datapoint on a numeric stream named temperature with a value of 32 would generate a Pusher event that looked like this:

  • channel name - private-m2x-temperature
  • event name - datapoint
  • payload - 32

With the default configuration, an incoming M2X location waypoint would generate a Pusher event that looked like this:

  • channel name - private-m2x-location
  • event name - waypoint
  • payload - {"latitude":-37.97884,"longitude":-57.54787,"elevation":5}

Pusher Sink Configuration

The credentials of the Pusher application will need to be configured in the integration in order for M2X to publish data on the user's behalf. If any of the following configuration fields are invalid, or if they later become invalid (for example, the Pusher application is deleted or the credentials are revoked and regenerated), the integration will fail to authenticate with the Pusher service, and the integration will become disabled on failure until the configuration is fixed and the integration is manually re-enabled.

  • app_id the user's application id reported by Pusher as the app_id.
  • app_key the key string associated with this Pusher application.
  • app_secret the secret string associated with this Pusher application.
  • app_cluster the 2- or 3-digit "shortcode" notation for the Pusher cluster where this Pusher application resides. If the application was created in the default Pusher cluster, then this field can be left out. Otherwise, it must match one of the "shortcodes" mentioned in the Pusher documentation for clusters.

The Pusher channel names used for publishing datapoint and waypoint events can be influenced using the following configuration field. This field is optional, with an implied default value if no explicit value is given.

  • channel_prefix the prefix to be prepended to all channel names. Note that channels starting with private- or presence- are treated as special cases by Pusher. The default value for this field is private-m2x-, meaning that the channel will be private by default.

List Integrations

GET /integrations

Retrieve the list of integrations owned by the account.

This endpoint requires a Master API key in the X-M2X-KEY header.

Responses

Success

200 OK
Content-Type: application/json

{ "integrations": [
  { "id": "48cd424a12787982b6c479de233d69b7",
    "url": "https://api-m2x.att.com/v2/integrations/48cd424a12787982b6c479de233d69b7",
    "type": "pusher_sink",
    "created": "2015-10-22T23:42:13.438Z",
    "updated": "2015-11-01T10:30:46.508Z" },
  { "id": "e6e3fe81399e03e943c9c6d39729d69b",
    "url": "https://api-m2x.att.com/v2/integrations/e6e3fe81399e03e943c9c6d39729d69b",
    "type": "pusher_sink",
    "created": "2015-10-22T23:18:41.272Z",
    "updated": "2015-11-01T11:42:36.743Z" } ] }

Create Integration

POST /integrations

Create a new integration. Accepts the following parameters:

  • name a string containing a user-defined name for the integration (required).
  • description a string containing the description of the integration (optional).
  • type one of the supported integration types (required).
  • config an object containing configuration fields and values, specific to the integration type chosen (optional or required based on type).
  • selectors an object containing zero or more criteria for selecting which devices will be part of the integration. If no criteria are specified, then all devices owned by the account will implicitly be part of the integration.

The selectors object currently accepts the following criteria:

  • devices takes an array of string device ids, all of which must be owned by the account. Those devices will be part of the integration, and all other devices owned by the account will be excluded (unless they are implied by another selector).
  • collections takes an array of collection ids, all of which must be owned by the account. Devices that are part of these collections will be part of the integration, and all other devices owned by the account will be excluded (unless they are implied by another selector).

This method requires that a Master API key is specified in the X-M2X-KEY header.

Request

Content-Type: application/json

{ "name": "My Integration",
  "description": "This is my first integration.",
  "type": "pusher_sink",
  "config": { "app_id": "502160",
              "app_key": "5f13aacee4a693056d64",
              "app_secret": "959dba39679ff39611cd",
              "app_cluster": "eu",
              "channel_prefix": "private-my-app-" },
  "selectors": { "devices": ["90e859acab77b43baec49868941c81d5",
                             "17ffc61f2b19065e8bf79360c8497780",
                             "d10ee5d6f2a424e863857c083819eae0"] } }

Responses

Success

201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/integrations/48cd424a12787982b6c479de233d69b7

{ "id": "48cd424a12787982b6c479de233d69b7",
  "url": "https://api-m2x.att.com/v2/integrations/48cd424a12787982b6c479de233d69b7",
  "name": "My Integration",
  "description": "This is my first integration.",
  "type": "pusher_sink",
  "status": "enabled",
  "config": { "app_id": "502160",
              "app_key": "5f13aacee4a693056d64",
              "app_secret": "959dba39679ff39611cd",
              "app_cluster": "eu",
              "channel_prefix": "private-my-app-" },
  "selectors": { "devices": ["90e859acab77b43baec49868941c81d5",
                             "17ffc61f2b19065e8bf79360c8497780",
                             "d10ee5d6f2a424e863857c083819eae0"] },
  "created": "2015-10-22T23:42:13.438Z",
  "updated": "2015-10-22T23:42:13.438Z" }

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": {
    "name": "not_present",
    "config": { "app_id": "not_present",
                "app_key": "not_present",
                "app_secret": "not_present" } } }

A developer will receive this response if one of the validations fail.

Update Integration Details

PUT /integrations/{id}

Update the details of an existing integration. Accepts the following parameters:

  • name a string containing a user-defined name for the integration (required).
  • description a string containing the description of the integration (optional).
  • type one of the supported integration types (required).
  • config an object containing configuration fields and values, specific to the integration type chosen (optional or required based on type).
  • selectors an object containing zero or more criteria for selecting which devices will be part of the integration. If no criteria are specified, then all devices owned by the account will implicitly be part of the integration.

This method requires that a Master API key is specified in the X-M2X-KEY header.

Request

Content-Type: application/json

{ "name": "My Integration",
  "description": "This is my first integration.",
  "type": "pusher_sink",
  "config": { "app_id": "502160",
              "app_key": "5f13aacee4a693056d64",
              "app_secret": "959dba39679ff39611cd",
              "app_cluster": "eu",
              "channel_prefix": "private-my-app-" },
  "selectors": { "devices": ["90e859acab77b43baec49868941c81d5",
                             "17ffc61f2b19065e8bf79360c8497780",
                             "d10ee5d6f2a424e863857c083819eae0"] } }

Responses

Success

204 No Content

Integration Not Found

404 Not Found
Content-Type: application/json

{ "message": "Integration Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified integration does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": {
    "config": { "app_id": "not_present",
                "app_key": "not_present",
                "app_secret": "not_present" } } }

A developer will receive this response if one of the validations fail.

View Integration Details

GET /integrations/{id}

Get the details of an existing integration.

This method requires that a Master API key is specified in the X-M2X-KEY header.

Responses

Success

200 OK
Content-Type: application/json
Location: https://api-m2x.att.com/v2/integrations/48cd424a12787982b6c479de233d69b7

{ "id": "48cd424a12787982b6c479de233d69b7",
  "url": "https://api-m2x.att.com/v2/integrations/48cd424a12787982b6c479de233d69b7",
  "name": "My Integration",
  "description": "This is my first integration.",
  "type": "pusher_sink",
  "status": "enabled",
  "info": {},
  "config": { "app_id": "502160",
              "app_key": "5f13aacee4a693056d64",
              "app_secret": "959dba39679ff39611cd",
              "app_cluster": "eu",
              "channel_prefix": "private-my-app-" },
  "selectors": { "devices": ["90e859acab77b43baec49868941c81d5",
                             "17ffc61f2b19065e8bf79360c8497780",
                             "d10ee5d6f2a424e863857c083819eae0"] },
  "created": "2015-10-22T23:42:13.438Z",
  "updated": "2015-11-01T11:42:36.743Z" }

Integration Not Found

404 Not Found
Content-Type: application/json

{ "message": "Integration Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified integration does not exist or belongs to another developer.

Update Integration Status

PUT /integrations/{id}/status

Update the enabled/disabled status of an existing integration. A disabled integration will not forward any data during the time it is disabled. A misconfigured or otherwise failing integration may be automatically disabled in case of failure, and it must be re-enabled using this endpoint. Accepts the following parameters:

  • status either enabled or disabled (required).
  • reason a string explaining the reason for the status change (optional).

This method requires that a Master API key is specified in the X-M2X-KEY header.

Request

Content-Type: application/json

{ "status": "enabled",
  "reason": "Re-enabling after fixing the configuration." }

Responses

Success

204 No Content

Integration Not Found

404 Not Found
Content-Type: application/json

{ "message": "Integration Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified integration does not exist or belongs to another developer.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "status": ["not_present"] } }

A developer will receive this response if one of the validations fail.

View Integration Status Details

GET /integrations/{id}/status

Get the most recent status change details of the integration.

This method requires that a Master API key is specified in the X-M2X-KEY header.

Responses

Success

200 OK
Content-Type: application/json

{ "status": "enabled",
  "reason": "Re-enabling after fixing the configuration.",
  "timestamp": "2015-11-01T11:42:36.743Z" }

Integration Not Found

404 Not Found
Content-Type: application/json

{ "message": "Integration Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified integration does not exist or belongs to another developer.

Delete Integration

DELETE /integrations/{id}

Delete an existing integration. The integration will no longer forward data, and all configuration will be permanently lost.

This method requires that a Master API key is specified in the X-M2X-KEY header.

Responses

Success

204 No Content

Integration Not Found

404 Not Found
Content-Type: application/json

{ "message": "Integration Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified integration does not exist or belongs to another developer.