mthurman/user_streams.md

## user_streams.md

      
    Raw
  

              user_streams.md
            
          
    User Streaming


Client makes authenticated connection to the user stream endpoint.
Authentication in headers or query string.
Endpoint: wss://stream-channel.app.net/stream/user (WebSocket) or https://stream-channel.app.net/stream/user (streaming HTTP).
If authentication fails, etc., client will be disconnected immediately with the appropriate HTTP error code.
The client can optionally supply an connection_id in the query string. The user stream endpoint will return the negotiated connection_id in HTTP headers (https) or initial message (websocket). This MAY be the same connection_id requested, if client was able to resume streaming on a previous endpoint. If it does NOT match, client should assume that subscriptions must be recreated, and should make efforts to backfill via the JSON API.
Other clients consuming the same connection_id will be disconnected. We will make a best-effort attempt to allow for replay of events upon reconnection; this behavior is designed to be available for approximately 600 seconds between connections.


Client subscribes to updates.
Based on the previous client state (if available), the client makes a number of backfill requests via the JSON API, as it would if streaming was unavailable. If a subscription is desired, the connection_id parameter can be supplied with each request. Creation of subscriptions is idempotent, but subscriptions are only created if: 1) count is zero or positive (defaults to 20), and 2) one of the following is true: (a) the since_id parameter was specified, the before_id parameter was not specified, and the more value in the returned meta object is false, (b) no pagination parameters were specified, or (c) no pagination is supported on that endpoint (e.g., user profile updates). The presence of the subscription_id value in the returned meta object indicates a subscription has been created or updated.
Requests for subscriptions can also contain a subscription_id, which is e.g., a UUID or short mnemonic string chosen by the client designed to uniquely identify that subscription. Client-supplied subscription_ids are considered opaque to App.net. This will be returned in the meta object of each returned message, as well as the HTTP response when a subscription is created, to help with message ordering. If a subscription_id is not supplied, one will be generated. The (connection_id, subscription_id) tuple must be globally unique, but subscription_ids can be reused between user streams. Each stream can have at most 50 subscriptions. A stream could be subscribed to the same API endpoint with multiple subscription_ids.
Clients may begin receiving events on the stream before the JSON API call returns, so it is recommended that stream consumers pre-allocate subscription IDs and queue any events received until after the final subscription call returns. Subscription requests with an existing subscription_id will overwrite any previous subscription on that endpoint.
Not all endpoints will be available for streaming. Here is the preliminary list of endpoints we expect to enable for user streaming:
 /stream/0/token (includes user profile updates, etc.)
 /stream/0/users/me/following
 /stream/0/users/me/followers
 /stream/0/users/me/posts
 /stream/0/users/me/mentions
 /stream/0/posts/stream
 /stream/0/posts/stream/unified
 /stream/0/channels (should include messages to subscribed channels.)
 /stream/0/users/me/channels/pm/num_unread
 /stream/0/channels/:channel_id/subscribers
 /stream/0/channels/:channel_id/messages
 /stream/0/users/me/files

Example usage:
 /stream/0/users/me?connection_id=sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf&subscription_id=ba14fab1-6021-43e1-a23d-ef8d54aef76a

Will return:
 {
     "meta": {
         "code": 200,
         "subscription_id": "ba14fab1-6021-43e1-a23d-ef8d54aef76a"
     },
     "data": {
         "... user object ...": ""
     }
 }

Another example:
 /stream/0/posts/stream/unified?connection_id=sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf

Will return:
 {
     "meta": {
         "code": 200,
         "subscription_id": "d3b72b23-f8d7-4108-a4f1-3aaa25328286",
         "marker": {
             "id": "5668480",
             "last_read_id": "5668480",
             "name": "unified",
             "percentage": 0,
             "updated_at": "2013-05-14T20:18:16Z",
             "version": "eMKC1BskFw8hL5q7FfTItiqgr4s"
         },
         "max_id": "5675954",
         "min_id": "5675037",
         "more": true
     },
     "data": [
         "... posts ..."
     ]
 }


Client consumes stream events.
Each stream message will be wrapped in a response envelope as if it were returned by the JSON API. This will include the subscription_id as returned above, and, if the original endpoint supported pagination, will be include pagination keys, including max_id, min_id and more keys as appropriate. more will always be false in the case of streaming events. Events may contain multiple data objects. As of 6/8/13, these keys are not currently included but will be soon.
Ordering is not guaranteed for events delivered on streams, but we aim to have the ordering be reasonably correct. Depending on your application, you may wish to reorder items for display.
Example message for the second subscription above:
 {
     "meta": {
         "code": 200,
         "subscription_id": "d3b72b23-f8d7-4108-a4f1-3aaa25328286",
         "max_id": "5675954",
         "min_id": "5675054",
         "more": false
     },
     "data": [
         {
             "... post 5675054 ...": ""
         }
     ]
 }

User stream consumers will receive stream marker updates for active subscriptions.


Client optionally modifies subscriptions.
The client can signal that it no longer wishes to use a stream by sending a DELETE request to /stream/0/users/me/streams/:connection_id. The endpoint will be disconnected in that case. In addition, individual subscriptions can be deleted by sending a DELETE request to /stream/0/users/me/streams/:connection_id/:subscription_id.