Skip to main content
Index

Subscriptions v2 APIs

These APIs support two kinds of communication channels, AWS IoT Core and Webhook. While AWS IoT Core enables the connection of multiple IoT devices to the cloud without the management of server infrastructure, Webhook uses mutual TLS (mTLS) authentication. Users can use only one of the channels for a single subscription.

mTLS certificate is used an extension of the TLS (former SSL) certificate for the server and client to authenticate each other. Equinix requires this trusted signed certificate from clients, similar to that provided by our services. Our subscription services offer you the additional option of connection verification. When a new batch of events is sent with each communication attempt, our subscription services use the certificates provided by the client to validate that the target contains them. 

GET Subscriptions

GET /smartview/v2/streaming/subscriptions

 Method  GET
 URL or End Point  /smartview/v2/streaming/subscriptions
 Headers  Authorization
 Query Parameters  Not applicable
 Body  Not applicable

 

This endpoint allows users to fetch the details of all streaming subscriptions for an organization.

Authorization token is the only required header that is passed to this API and a response is received.

 

If you are unaware of how to obtain an authorization key, refer to Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to view the subscriptions details for the real-time stream and a JSON response containing the result. 

 

curl -X 

GET "https://api.equinix.com/smartview/v2/streaming/subscriptions"     

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2" 

 

[
  {
    "id": "606349eca6171829c70d8777",

    "status": "PENDING";
    "messageType": {
      "asset": [
        {
          "accountNumber": "135888",
          "ibx": [
            "DE2"
          ],
          "assetClassification": [
            "MECHANICAL"
          ],
          "assetId": [
            "string"
          ]
        }
      ],
      "environmental": [
        {
          "accountNumber": "135888",
          "ibx": [
            "DE2"
          ],
          "level": [
            "ZONE"
          ]
        }
      ],
      "power": [
        {
          "accountNumber": "135888",
          "ibx": [
            "DE2"
          ]
        }
      ],
      "systemAlert": [
        {
          "accountNumber": "135888",
          "ibx": [
            "DE2"
          ],
          "assetClassification": [
            "MECHANICAL"
          ],
          "conditionName": [
            "ALARM"
          ]
        }
      ],
      "customAlert": [
        {
          "accountNumber": "135888",
          "ibx": [
            "DE2"
          ],
          "user": "abc"
        }
      ]
    },
    "channel": {
      "channelType": "AWS_IOT_CORE",
      "awsIotCoreChannelConfiguration": {
        "roleArnToAssume": "arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123",
        "url": "https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com"
      }
    }
    "orgId": "123",
    "createdBy": "abc",
    "createdDateTime": "2019-08-24T14:15:22Z",
    "updatedBy": "abc",
    "updatedDateTime": "2019-08-24T14:15:22Z"
  }
]

 

Alternate configuration for Webhook is shown in the screenshot below.

 

      "channelType": "WEBHOOK",
      "webhookChannelConfiguration": {
        "sslCertificate": "ZkFzZLY1IGRpY31kZXI=",
        "url": "https://client/event/endpoint",
        "numberOfRetries": 1,
        "numberOfConcurrentCalls": 20,
        "batchSize": 5
      }

 

The description of the response payload is as follows:

 

Field name Type Example Description
id string 606349eca6171829c70d8777 Unique identifier of the subscription
status string PENDING, ACTIVE, FAILED Status of the subscription (Pending: Subscription request is accepted for configuration setup, Active: Subscription is active and events are expected soon, Failed: An error occurred and the subscription should be removed)
messageType object messageType{...} Message type for the subscription that defines the IBX details from which to expect particular events
asset array asset[{...}] List of asset message type to subscribe
ibx string DE2 IBX Code
accountNumber string 135888 Customer account number
assetId array assetId["string"] Unique identifier for the asset
assetClassification array ["ELECTRICAL", "MECHANICAL", "ENVIRONMENTAL"] Classification of assets - Asset Classification value if specified, otherwise all allowable classifications
environmental array environmental[{...}] List of environmental message type to subscribe
level string IBX, ZONE, CAGE If not provided in the request, subscription includes all environmental messages at the IBX, zone, and cage levels.
power array power[{...}] List of power message type to subscribe
conditionName array ["ALARM", "HIGH", "HIGH_HIGH", "LOW", "LOW_LOW", "WARNING"] Alarm condition of the asset
systemAlert array systemAlert[{...}] List of system alert message type to subscribe
customAlert array customAlert[{...}] List of custom alert message type to subscribe
user string abc User associated with the subscription
channel object channel{...} This defines the technical parameters of a new subscription - Subscriptions can be created using one channel
channelType string AWS_IOT_CORE, WEBHOOK Type of communication channel used for the subscription
awsIotCoreChannelConfiguration object awsIotCoreChannelConfiguration{...} The configuration for an 'AWS_IOT_CORE' channel
roleArnToAssume string arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123 Role to be used for IoT configuration
url string https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com
https://client/event/endpoint
The URL for AWS_IOT_CORE or WEBHOOK, to which events of subscription will be sent
webhookChannelConfiguration object webhookChannelConfiguration{...} The configuration for a 'WEBHOOK' channel
sslCertificate string ZkFzZLY1IGRpY31kZXI Base64 form of client public certificate chain in PEM format
numberOfRetries integer default value: 3
data range: 1 to 5
Number of times the subscription tries to send messages until it is marked as ‘Retried’ (no longer near real-time) - Our internal process tries to resend the message later; if the endpoint URL is unavailable, then messages will be moved to DLQ.
numberOfConcurrentCalls integer default value: 25
data range: 20 to 50

Upper bound of concurrent workers sending messages to the given url

batchSize

integer default value: 10
data range: 5 to 20

Upper (soft) bound for number of messages in a single payload

orgId string 123 Organization identifier associated with the subscription
createdBy string abc Details of who created the subscription
createdDateTime string 2019-08-24T14:15:22Z Date and time of when the subscription was created
updatedBy string abc Details of who last updated the subscription
updatedDateTime string 2019-08-24T14:15:22Z Date and time of when the subscription was last updated

 

If you get the “Access Denied” error, contact your local Equinix Service Desk for IBX SmartView Portal access.

GET Subscriptions by Id

GET /smartview/v2/streaming/subscriptions/{id}

 Method  GET
 URL or End Point  /smartview/v2/streaming/subscriptions/{id}
 Headers  Authorization
 Path Parameters  id
 Query Parameters  Not applicable
 Body  Not applicable

 

This endpoint allows users to fetch details of a specific streaming subscription for a given organization.

Authorization token is the only header that is passed to this API and a response is received. 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to view the requested subscriptions details for the real-time stream and a JSON response containing the result. 

 

curl -X 

GET "https://api.equinix.com/smartview/v2/streaming/subscriptions/606349eca6171829c70d8777"     

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2" 

 

{
  "id": "606349eca6171829c70d8777",

  "status": "ACTIVE",
  "messageType": {
    "asset": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "assetClassification": [
          "MECHANICAL"
        ],
        "assetId": [
          "string"
        ]
      }
    ],
    "environmental": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "level": [
          "ZONE"
        ]
      }
    ],
    "power": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ]
      }
    ],
    "systemAlert": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "assetClassification": [
          "MECHANICAL"
        ],
        "conditionName": [
          "ALARM"
        ]
      }
    ],
    "customAlert": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "user": "abc"
      }
    ]
  },
  "channel": {
    "channelType": "AWS_IOT_CORE",
    "awsIotCoreChannelConfiguration": {
      "roleArnToAssume": "arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123",
      "url": "https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com"
    }
  },
  "orgId": "123",
  "createdBy": "abc",
  "createdDateTime": "2019-08-24T14:15:22Z",
  "updatedBy": "abc",
  "updatedDateTime": "2019-08-24T14:15:22Z"
}

 

Alternate configuration for Webhook is shown in the screenshot below.

 

      "channelType": "WEBHOOK",
      "webhookChannelConfiguration": {
        "sslCertificate": "ZkFzZLY1IGRpY31kZXI=",
        "url": "https://client/event/endpoint",
        "numberOfRetries": 1,
        "numberOfConcurrentCalls": 20,
        "batchSize": 5
      }

 

The description of the response payload is as follows:

 

Field name Type Example Description
id string 606349eca6171829c70d8777 Unique identifier of the subscription
status string PENDING, ACTIVE, FAILED Status of the subscription (Pending: Subscription request is accepted for configuration setup, Active: Subscription is active and events are expected soon, Failed: An error occurred and the subscription should be removed)
messageType object messageType{...} Message type for the subscription that defines the IBX details from which to expect particular events 
asset array asset[{...}] List of asset message type to subscribe
ibx string DE2 IBX Code
accountNumber string 135888 Customer account number
assetId array assetId["string"] Unique identifier for the asset
assetClassification array ["ELECTRICAL", "MECHANICAL", "ENVIRONMENTAL"] Classification of assets - Asset Classification value if specified, otherwise all allowable classifications
environmental array environmental[{...}] List of environmental message type to subscribe
level string IBX, ZONE, CAGE If not provided in the request, subscription includes all environmental messages at the IBX, zone, and cage levels.
power array power[{...}] List of power message type to subscribe
conditionName array ["ALARM", "HIGH", "HIGH_HIGH", "LOW", "LOW_LOW", "WARNING"] Alarm condition of the asset
systemAlert array systemAlert[{...}] List of system alert message type to subscribe
customAlert array customAlert[{...}] List of custom alert message type to subscribe
user string abc User associated with the subscription
channel object channel{...} This defines the technical parameters of a new subscription - Subscriptions can be created using one channel
channelType string AWS_IOT_CORE, WEBHOOK Type of communication channel used for the subscription
awsIotCoreChannelConfiguration object awsIotCoreChannelConfiguration{...} The configuration for an 'AWS_IOT_CORE' channel
roleArnToAssume string arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123 Role to be used for IoT configuration
url string https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com
https://client/event/endpoint
The URL for AWS_IOT_CORE or WEBHOOK, to which events of subscription will be sent
webhookChannelConfiguration object webhookChannelConfiguration{...} The configuration for a 'WEBHOOK' channel
sslCertificate string ZkFzZLY1IGRpY31kZXI Base64 form of client public certificate chain in PEM format
numberOfRetries integer default value: 3
data range: 1 to 5
Number of times the subscription tries to send message until it is marked as ‘Retried’ (no longer near real-time) - Our internal process tries to resend the messages later; if the endpoint URL is unavailable, then messages will be moved to DLQ.
numberOfConcurrentCalls integer default value: 25
data range: 20 to 50

Upper bound of concurrent workers sending messages to the given url

batchSize

integer default value: 10
data range: 5 to 20

Upper (soft) bound for number of messages in a single payload

orgId string 123 Organization identifier associated with the subscription
createdBy string abc Details of who created the subscription
createdDateTime string 2019-08-24T14:15:22Z Date and time of when the subscription was created
updatedBy string abc Details of who last updated the subscription
updatedDateTime string 2019-08-24T14:15:22Z Date and time of when the subscription was last updated

 

If you get the “Access Denied” error, contact your local Equinix Service Desk for IBX SmartView Portal access.

POST Subscriptions

POST /smartview/v2/streaming/subscriptions

 Method  POST
 URL or End Point  /smartview/v2/streaming/subscriptions
 Headers  Authorization
 Query Parameters  Not applicable
 Body

 messageType, asset, accountNumber, ibx, assetClassification, assetId, environmental, level, power, 

 systemAlert, conditionName, customAlert, user, channel, channelType, awsIotCoreChannelConfiguration,

 roleArnToAssume, url, webhookChannelConfiguration, sslCertificate, numberOfRetries, batchSize,

 numberOfConcurrentCalls


This endpoint allows users to define and create new streaming subscriptions for an organization. User can specify the events for each Account-IBX combination and the real-time stream integration parameters as configurations to be available as real-time streams in the request.

Authorization token is the only header that is passed to this API and a response is received.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshots show a sample curl request to create a new streaming subscription for an organization, and a successful HTTP response containing the location header.

 

curl -X 

POST "https://api.equinix.com/smartview/v2/streaming/subscriptions"     

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2"

-d '{
  "messageType": {
    "asset": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "assetClassification": [
          "MECHANICAL"
        ],
        "assetId": [
          "string"
        ]
      }
    ],
    "environmental": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "level": [
          "ZONE"
        ]
      }
    ],
    "power": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ]
      }
    ],
    "systemAlert": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "assetClassification": [
          "MECHANICAL"
        ],
        "conditionName": [
          "ALARM"
        ]
      }
    ],
    "customAlert": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "user": "abc"
      }
    ]
  },
  "channel": {
    "channelType": "AWS_IOT_CORE",
    "awsIotCoreChannelConfiguration": {
      "roleArnToAssume": "arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123",
      "url": "https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com"
    }
  }
}' 

 

Alternate configuration for Webhook is shown in the screenshot below.

 

    "channelType": "WEBHOOK",
    "webhookChannelConfiguration": {
      "sslCertificate": "ZkFzZLY1IGRpY31kZXI=",
      "url": "https://client/event/endpoint",
      "numberOfRetries": 1,
      "numberOfConcurrentCalls": 20,
      "batchSize": 5
    }

 

The description of the body parameters is as follows:

 

Body parameter name Mandatory Type Example Description
messageType Y object messageType{...} Message type for the subscription that defines the IBX details from which to expect events
asset N array asset[{...}] List of asset message type to subscribe
ibx Y string DE2 IBX Code
accountNumber Y string 135888 Customer account number
assetId N array assetId["string"] Unique identifier for the asset
assetClassification N array ["ELECTRICAL", "MECHANICAL", "ENVIRONMENTAL"] Classification of assets - Asset Classification value if specified, otherwise all allowable classifications
environmental N array environmental[{...}] List of environmental message type to subscribe
level N string IBX, ZONE, CAGE If not provided in the request, subscription includes all environmental messages at the IBX, zone, and cage levels.
power N array power[{...}] List of power message type to subscribe
conditionName N array ["ALARM", "HIGH", "HIGH_HIGH", "LOW", "LOW_LOW", "WARNING"] Alarm condition of the asset
systemAlert N array systemAlert[{...}] List of system alert message type to subscribe
customAlert N array customAlert[{...}] List of custom alert message type to subscribe
user N string abc User associated with the subscription
channel N object channel{...} Defines the technical parameters of the new subscription - Subscriptions can be created using one channel
channelType Y string AWS_IOT_CORE, WEBHOOK Type of communication channel used for the subscription
awsIotCoreChannelConfiguration N object awsIotCoreChannelConfiguration{...} The configurations for an 'AWS_IOT_CORE' channel
roleArnToAssume Y string arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123 Role to be used for IoT configuration
url Y string https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com
https://client/event/endpoint
The URL for AWS_IOT_CORE or WEBHOOK, to which events of subscription will be sent
webhookChannelConfiguration N object webhookChannelConfiguration{...} The configuration for a 'WEBHOOK' channel
sslCertificate N string ZkFzZLY1IGRpY31kZXI Base64 form of client public certificate chain in PEM format
numberOfRetries N integer default value: 3
data range: 1 to 5
Number of times the subscription tries to send messages until it is marked as ‘Retried’ (no longer near real-time) - Our internal process tries to resend the message later; if the endpoint URL is unavailable, then messages will be moved to DLQ.
numberOfConcurrentCalls N integer default value: 25
data range: 20 to 50

Upper bound of concurrent workers sending messages to the given url

batchSize

N integer default value: 10
data range: 5 to 20

Upper (soft) bound for number of messages in a single payload

 

HTTP/1.1 201 Created
Location: /smartview/v2/streaming/subscriptions/607460c5e4a78360425bca63

 

If you get the “Access Denied” error, contact your local Equinix Service Desk for IBX SmartView Portal access.

PUT Subscriptions

PUT /smartview/v2/streaming/subscriptions/{id}

 Method  PUT
 URL or End Point  /smartview/v2/streaming/subscriptions/{id}
 Headers  Authorization
 Query Parameters  Not applicable
 Path Parameters  id
 Body

 messageType, asset, accountNumber, ibx, assetClassification, assetId, environmental, level, power, 

 systemAlert, conditionName, customAlert, user, channel, channelType, awsIotCoreChannelConfiguration,

 roleArnToAssume, url, webhookChannelConfiguration, sslCertificate, numberOfRetries, batchSize,

 numberOfConcurrentCalls

 

This endpoint allows users to modify and update an existing streaming subscription for an organization.

Authorization token is the only header that is passed to this API and a response is received based on the parameters passed.

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshot shows a sample curl request to update the details of an identified subscription for the real-time stream. 

 

curl -X 

PUT "https://api.equinix.com/smartview/v2/streaming/subscriptions/{id}"     

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2"

-d '{
  "messageType": {
    "asset": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "assetClassification": [
          "MECHANICAL"
        ],
        "assetId": [
          "string"
        ]
      }
    ],
    "environmental": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "level": [
          "ZONE"
        ]
      }
    ],
    "power": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ]
      }
    ],
    "systemAlert": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "assetClassification": [
          "MECHANICAL"
        ],
        "conditionName": [
          "ALARM"
        ]
      }
    ],
    "customAlert": [
      {
        "accountNumber": "135888",
        "ibx": [
          "DE2"
        ],
        "user": "abc"
      }
    ]
  },
  "channel": {
    "channelType": "AWS_IOT_CORE",
    "awsIotCoreChannelConfiguration": {
      "roleArnToAssume": "arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123",
      "url": "https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com"
    }
  }
}' 

 

Alternate configuration for Webhook is shown in the screenshot below.

 

    "channelType": "WEBHOOK",
    "webhookChannelConfiguration": {
      "sslCertificate": "ZkFzZLY1IGRpY31kZXI=",
      "url": "https://client/event/endpoint",
      "numberOfRetries": 1,
      "numberOfConcurrentCalls": 20,
      "batchSize": 5
    }

 

The description of the body parameters is as follows:

 

Body parameter name Mandatory Type Example Description
messageType Y object messageType{...} Message type for the subscription that defines the IBX details from which to expect events
asset N array asset[{...}] List of asset message type to subscribe
ibx Y string DE2 IBX Code
accountNumber Y string 135888 Customer account number
assetId N array assetId["string"] Unique identifier for the asset
assetClassification N array ["ELECTRICAL", "MECHANICAL", "ENVIRONMENTAL"] Classification of assets - Asset Classification value if specified, otherwise all allowable classifications
environmental N array environmental[{...}] List of environmental message type to subscribe
level N string IBX, ZONE, CAGE If not provided in the request, subscription includes all environmental messages at the IBX, zone, and cage levels.
power N array power[{...}] List of power message type to subscribe
conditionName N array ["ALARM", "HIGH", "HIGH_HIGH", "LOW", "LOW_LOW", "WARNING"] Alarm condition of the asset
systemAlert N array systemAlert[{...}] List of system alert message type to subscribe
customAlert N array customAlert[{...}] List of custom alert message type to subscribe
user N string abc User associated with the subscription
channel N object channel{...} Defines the technical parameters of the new subscription - Subscriptions can be created using one channel
channelType Y string AWS_IOT_CORE, WEBHOOK Type of communication channel used for the subscription
awsIotCoreChannelConfiguration N object awsIotCoreChannelConfiguration{...} The configurations for an 'AWS_IOT_CORE' channel
roleArnToAssume Y string arn:aws:iam::543586087123:role/publish-from-partner-role-543586087123 Role to be used for IoT configuration
url Y string https://b4c3mzxe8syvhd-ats.iot.us-west-2.amazonaws.com
https://client/event/endpoint
The URL for AWS_IOT_CORE or WEBHOOK, to which events of subscription will be sent
webhookChannelConfiguration N object webhookChannelConfiguration{...} The configuration for a 'WEBHOOK' channel
sslCertificate N string ZkFzZLY1IGRpY31kZXI Base64 form of client public certificate chain in PEM format
numberOfRetries N integer default value: 3
data range: 1 to 5
Number of times the subscription tries to send messages until it is marked as ‘Retried’ (no longer near real-time) - Our internal process tries to resend the message later; if the endpoint URL is unavailable, then messages will be moved to DLQ.
numberOfConcurrentCalls N integer default value: 25
data range: 20 to 50

Upper bound of concurrent workers sending messages to the given url

batchSize

N integer default value: 10
data range: 5 to 20

Upper (soft) bound for number of messages in a single payload

 

If you get the “Access Denied” error, contact your local Equinix Service Desk for IBX SmartView Portal access.

DELETE Subscriptions

DELETE /smartview/v2/streaming/subscriptions/{id}

 Method  DELETE
 URL or End Point  /smartview/v2/streaming/subscriptions/{id}
 Headers  Authorization
 Query Parameters  Not applicable
 Path Parameters  id
 Body  Not applicable

 

This API allows users to delete and remove an existing streaming subscription for an organization. Events will no longer be available for the subscription once a delete request is received.

Authorization token is the only header that is passed to this API and a response is received. 

 

If you are unaware of how to obtain an authorization key, refer Requesting Access and Refresh tokens under Getting Started.

 

The following screenshot shows a sample curl request to delete the subscriptions details for the real-time stream. 

 

curl -X 

DELETE "https://api.equinix.com/smartview/v2/streaming/subscriptions/606349eca6171829c70d8777"     

-H "authorization: Bearer asxQMSbBwcNzI2fCCNwSwTh3phV2" 

 

If you get the “Access Denied” error, contact your local Equinix Service Desk for IBX SmartView Portal access.