Connect to a Stream

GET /streams/:id/connect

A request to this endpoint will initiate the streaming of events for the customer using Server-Sent Events (SSE). This creates a long-lived HTTP connection where a poke event will be sent every 5 seconds. Data will be sent in a data event. If multiple connections are established the stream of events will be distributed across those connections. Validic allows up to 20 client connections to each streaming resource.
Please be aware that a client disconnect initiates internal processing to rebalance the stream across any remaining connected clients. Validic will not internally release the available connection until the rebalance processing has been completed. In most situations this should not be an issue, however, if the maximum number of clients are connected, a client disconnect followed by a quick reconnect may result in an HTTP 422 error indicating that the max number of client connections has been exceeded for the stream. The customer should attempt several retries with a back-off to accommodate this scenario.

Please note that Validic streams operate from an at least once message delivery expectation. It is up to the customer to ensure idempotent handling of redelivered messages. Reconnecting after a disconnect is the most common example of message redelivery as Validic tries to ensure no messages are lost due to network issues leading to client/server disconnections.

A Content-Type response header of text/event-stream will be returned, indicating a long-lived HTTP connection, in which data will be streamed to the client.
##HTTP Response Status

Response CodeDescription
200 (OK)Indicates the request was received and a result was returned.
400 (Bad Request)Indicates that the request was invalid.
404 (Not Found)Indicates that the stream could not be found.
422 (Unprocessable Entity)An error occurred and an error response has been sent with details.

Code Samples

https://streams.v2.validic.com/streams/598372650b11e700018284ab/connect?token=6f46db36dd6543d2b82d91698fcd0896
event:data 
data:{  
   "category":"daily",
   "checksum":"ff11bfe05bfd5296a2c4f7c41ec0980d",
   "created_at":"2017-08-04T12:07:15.439Z",
   "deleted_at":null,
   "end_time":"2017-08-04T03:59:59Z",
   "id":"f658f824ab7c41ffd7bb0607d14f76ab",
   "log_id":"2017-08-03",
   "metrics":[  
      {  
         "origin":"unknown",
         "type":"active_duration",
         "unit":"s",
         "value":135.0
      },
      {  
         "origin":"unknown",
         "type":"basal_energy_burned",
         "unit":"kcal",
         "value":2371.7412956
      },
      {  
         "origin":"unknown",
         "type":"distance",
         "unit":"m",
         "value":1510.36558533
      },
      {  
         "origin":"unknown",
         "type":"active_energy_burned",
         "unit":"kcal",
         "value":295.203469907
      },
      {  
         "origin":"unknown",
         "type":"steps",
         "unit":"count",
         "value":1877
      },
      {  
         "origin":"unknown",
         "type":"energy_burned",
         "unit":"kcal",
         "value":2666.944765507
      }
   ],
   "offset_origin":"source",
   "segments":[  

   ],
   "source":{  
      "type":"jawbone"
   },
   "start_time":"2017-08-03T04:00:00Z",
   "type":"summary",
   "user":{  
      "organization_id":"597752338a5da500014a1f9a",
      "uid":"277040620-sel",
      "user_id":"597769108a5da500014a1fa8"
   },
   "user_notes":[  

   ],
   "utc_offset":-14400,
   "version":"1.0"
}

event:poke 
data:{  
   "ts":"2017-08-04T18:17:34.610Z",
   "stream":"598372650b11e700018284ab",
   "members":{  
      "count":1,
      "max":20
   }
}

event:poke 
data:{  
   "ts":"2017-08-04T18:17:39.614Z",
   "stream":"598372650b11e700018284ab",
   "members":{  
      "count":1,
      "max":20
   }
}

Response Field Descriptions

versionstringIndicates the resource payload version. Validic will make future updates to the structure of the resource payload where breaking changes will receive a new version.
tsstringTime stamp which identifies when data entered the stream.
streamstringUnique ID assigned to stream
membersstringA member object that contains member specific information.
members>countintegerNumber of users contained in stream.
members>maxintegerMax number of users in stream.
event:pokestringA pke event acts as a "heart beat" which indicates the stream is active.
idstringUnique identifier for the record.
checksumstringA derived value useful when comparing records with the same id for data updates.
typestringThe Validic Resource type. For Measurement records the type will be measurements.
start_timestringThe start time of the event represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ.
end_timestringThe end time of the event represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ.
utc_offsetintegerThe offset in seconds from UTC.
offset_originstringThe source of the UTC offset. Valid values: source (UTC offset received from the original record), profile (UTC offset received from the source's user profile), user_defined (UTC offset provided by user's time zone selection upon authorization through the Validic Marketplace).
userobjectA User object that contains identifiers related to the user.
user>uidstringThe customer's user ID.
user>user_idstringValidic user ID.
user>customer_idstringValidic customer ID.
log_idstringThe unique identifier for the record provided by the source.
sourceA source object that contains source specific information.
source>typestringThe source Validic retrieved the data from.
source>deviceobjectA device object containing information about the device that generated the data if available.
source>device>namestringThe name of the device.
source>device>typestringThe type of the device.
namestringA free form field that defines the meal type or food type for the record.
categorystringThe category of the meal. Valid values: food, meal, other.
metricsarrayAn array of Metrics. Refer to the Metrics documentation for further information.
segmentsarrayAn array of Segments. A more granular view of the items that compose the nutrition event.
segment>namestringA free form field that defines the food type for the segment.
segment>metricsarrayMetrics for the given segment.
created_atstringThe record processed time represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ.

What’s Next