<< Click to Display Table of Contents >> Navigation:  The API > JSON API > Real Time Communication > From Gateway to Client: Streaming API > Connecting to a streaming Endpoint

Overview

Establishing a connection to the streaming APIs means long polling a certain HTTP resource (/devices/stream), and parsing the response incrementally. Conceptually, you can think of it as downloading an infinitely long text file over HTTP.

Connecting

To connect to the streaming API, form a HTTP request and consume the resulting stream for as long as is practical. The Gateway will keep the connection open indefinitely, barring server-side error, excessive client-side lag or network hiccups.

The method to form an HTTP request and parse the response will be different for every language or framework, so consult the documentation for the HTTP library you are using.

Some HTTP client libraries only return the response body after the connection has been closed by the server. These clients will not work for accessing the Streaming API. You must use an HTTP client that will return response data incrementally. Most robust HTTP client libraries will provide this functionality. The Apache HttpClient will handle this use case, for example.

Disconnections

The Gateway will never close a connection.

Reconnecting

Once an established connection drops, attempt to reconnect immediately. If the reconnect fails, slow down your reconnect attempts according to the type of error experienced:

Back off linearly for TCP/IP level network errors. These problems are generally temporary and tend to clear quickly. Increase the delay in reconnects by 250ms each attempt, up to 16 seconds.

Back off exponentially for HTTP errors for which reconnecting would be appropriate. Start with a 5 second wait, doubling each attempt, up to 320 seconds.