Hologram_BrandFINAL_RGB

Cloud Services Router API Documentation (Beta)

Overview

Our Cloud Services Router provides a service for dynamically routing data based upon content, and simplifies the task of complex device/service integrations. This document provides Cloud Services Router developer and API documentation that explains how to integrate the data from a device or software application with our Cloud Services Router. This document is useful for device and software developers.

For more information regarding how to configure the Cloud Services Router to deliver existing device/software data to one or more destination applications/services, please see the Cloud Services Router User’s Guide.


Using the API

API Endpoints

We offer three API endpoints – one for low-level, TCP/IP socket connectivity (which minimizes the amount of cellular data needing to be consumed); one that is a web-friendly, RESTful HTTP endpoint; and one that accepts data over SMS messages sent to a special destination long code

Low-level IP Endpoint
Our low-level, non-REST TCP/IP API endpoint (characters sent and received over low-level socket connections) allows devices to consume very minimal data compared to REST and HTTP
IP: 23.253.146.203 (cloudsocket.konekt.io), Port: 9999
REST HTTP API Endpoint

Our RESTful HTTP API endpoint is web-friendly (HTTP GET/POST, responses are in JSON format) and makes higher-level integrations easy

SMS Long Code API Endpoint

Our SMS Long Code API endpoint allows devices that are SMS capable and utilizing our cellular connectivity offering to use well-supported circuit-switched SMS messages to send data payloads to our Cloud and (ultimately) to configurable final destinations (note that this will incur fees at SMS rates, which are typically more costly than data rates, and is preferable only when needed for integration purposes)

Devices send SMS to: 310000202

Low-level TCP/IP Endpoint Authentication

Authentication for our Low-level TCP/IP Endpoint and our REST Endpoint can be performed by providing Source Credentials, which consist of a 4-byte Source ID and a 4-byte Key. Source Credentials are random bytes created by our servers, and new Source Credentials can be created on the Services page of our Portal. Note that unique Source Credentials should be used for each device.

REST HTTP Endpoint Authentication

Our REST HTTP Endpoint is coming soon!

SMS Long Code Endpoint Authentication

Devices utilizing our cellular network to send data to our Cloud Services Router via circuit-switched SMS do not provide credentials, as they are authenticated via their SIM cards and our cellular network in order to send SMS messages


Injecting Data

Injecting Data via Low-level TCP/IP

There are currently three different data formats accepted by our Low-level IP Endpoint, in order to offer flexibility between overhead costs and available features.

JSON Expanded

Most human-readable, but also consumes the most data usage
{"source":"ABCD", "checksum":"WXYZ", "data":"Hello, World!", "tags":["TAG1","TAG2"]}
Example Response:
[0,0]

  • ABCD is a 4-byte (4-character) Source Credential authentication identifier for the device, obtainable on the Services tab within the Portal
  • WXYZ is a 4-byte (4-character) Source Credential authentication key for the device, obtainable on the Services tab within the Portal. For now, pre-shared keys are the only supported authentication mechanism for devices; however, other authentication/validation mechanisms will soon be supported in the checksum field.
  • The value associated with the data key is used to store the device’s data payload to be routed through our cloud
  • Hello, World! represents a sample data payload
  • The tags key contains tags (topics) that this data will be published to. Supported values are a JSON ordered list of string tag names or a single string tag name. Tags are used to trigger different routing rules and should be used liberally to describe the context of the data source, the event that triggered the data, the reason for sending the data, and any other information that can be useful for determining conditions under which our cloud should route the data.
  • Responses are JSON integer arrays of length 2; on success, a response of [0,0] should be received

JSON Abbreviated

Contains full feature set as the JSON Expanded format, but consumes less data usage
{"s":"AAAA", "c":"BBBB", "d":"Hello, World!", "t":["TAG1","TAG2"]}
Example Response:
[0,0]
  • ABCD is a 4-byte (4-character) Source Credential authentication identifier for the device, obtainable on the Services tab within the Portal
  • WXYZ is a 4-byte (4-character) Source Credential authentication key for the device, obtainable on the Services tab within the Portal. For now, pre-shared keys are the only supported authentication mechanism for devices; however, other authentication/validation mechanisms will soon be supported in the checksum field.
  • The value associated with the d key is used to store the device’s data payload to be routed through our cloud
  • Hello, World! represents a sample data payload
  • The t key contains tags (topics) that this data will be published to. Supported values are a JSON ordered list of string tag names or a single string tag name. Tags are used to trigger different routing rules and should be used liberally to describe the context of the data source, the event that triggered the data, the reason for sending the data, and any other information that can be useful for determining conditions under which our cloud should route the data.
  • Responses are JSON integer arrays of length 2; on success, a response of [0,0] should be received

 

JSON Minimal

Consumes the least amount of data, but also offers only a minimal set of features
Coming soon!

Basic Binary

Consumes the least amount of data, but also offers only a minimal set of features
Coming soon!

Injecting Data via REST HTTP

Coming soon!

Injecting Data via SMS

SMS messages sent to our long code 310000202 will have a Base64-encoded version of their SMS body placed as the data payload into our Cloud Services Router.

Hello, World!
  • Hello, World! is the SMS body in standard SMS format
  • {“body”: “SGVsbG8sIFdvcmxkIQ==”, “status”: “delivered”, “direction”: “DO”, “received”: “2014-11-11 01:02:44”, “destination”: “310000202”, “type”: “T”, “id”: 262706444} is the CSR-SMS JSON-formatted object that will appear as the data payload in the Cloud Services Router
  • SGVsbG8sIFdvcmxkIQ== is the Base64-encoded version of the Hello, World! SMS message body
  • 2014-11-11 01:02:44 is the timestamp for when the SMS was received by the carrier network for delivery
  • 262706444 is an identifier for the SMS message