Connect to a Stream

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 3 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 Code	Description
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.

Data Event 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


version	string	Indicates the resource payload version. Validic will make future updates to the structure of the resource payload where breaking changes will receive a new version.
ts	string	Time stamp which identifies when data entered the stream.
stream	string	Unique ID assigned to stream
members	string	An array that contains member specific connection information.
members>count	integer	Number of connections to a given stream.
members>max	integer	Max number of connections for a stream.
event:poke	string	A poke event acts as a "heart beat" which indicates the stream is active.
id	string	Unique identifier for the record.
checksum	string	A derived value useful when comparing records with the same `id` for data updates.
type	string	The Validic Resource type. For Measurement records the type will be `measurements`.
start_time	string	The start time of the event represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ.
end_time	string	The end time of the event represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ.
utc_offset	integer	The offset in seconds from UTC.
offset_origin	string	The 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).
user	object	A User object that contains identifiers related to the user.
user>uid	string	The customer's user ID.
user>user_id	string	Validic user ID.
user>customer_id	string	Validic customer ID.
log_id	string	The unique identifier for the record provided by the source.
source		A source object that contains source specific information.
source>type	string	The source Validic retrieved the data from.
source>device	object	A device object containing information about the device that generated the data if available.
source>device>name	string	The name of the device.
source>device>type	string	The type of the device.
name	string	A free form field that defines the meal type or food type for the record.
category	string	The category of the meal. Valid values: `food`, `meal`, `other`.
metrics	array	An array of Metrics. Refer to the Metrics documentation for further information.
segments	array	An array of Segments. A more granular view of the items that compose the nutrition event.
segment>name	string	A free form field that defines the food type for the segment.
segment>metrics	array	Metrics for the given segment.
created_at	string	The record processed time represented in UTC. Format: YYYY-MM-DDThh:mm:ssZ.