Control Streams for Site Streams

Control Streams provides a REST-based interface that allows a developer to query and modify the state of a specific Site Streams connection. Use the same three-legged OAuth patterns you use to connect to Site Streams, where the access token used belongs to the user that owns the application that bears access tokens for the users you’re streaming on behalf of.

At this time, you can use control streams to:

• Obtain information about the current state of a stream
• Add additional authenticated users to a Site Streams connection
• Remove authenticated users from a Site Streams connection
• Obtain information about the followings of specific users present on a Site Streams connection

Determining your stream_id and control_uri

After opening a connection to Site Streams, you will be streamed a new event that will declare a specific URI path for you to base control requests from in the format of /:version/site/c/:stream_id. You will receive this URI path in a “control_uri” node from the “control” event.

{
  "control": {
    "control_uri":"/1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f"
  }
}

The segment of this path following “/1.1/site/c/” is the unique stream_id for this particular stream. Once you disconnect from this stream, the stream_id will no longer be valid. In the above example, the stream_id would be “1_1_54e345d655ee3e8df359ac033648530bfbe26c5f”.

Note that the control message will not necessarily be the first message delivered on a Site Stream connection. Construct your code to be able to handle cases where other types of messages may be delivered first.

Obtain information the current state of a stream

URI format: GET /1.1/site/c/:stream_id/info.json

Using the stream_id from the control message, you can build a GET request to obtain information on the users currently represented in your stream, how the connection is disposed, whether you have RW+DM access for a specific user, and other miscellaneous information that may or may not be pertinent to you at this time.

This is the most reliable way to determine which users are being streamed over a particular connection.

GET /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/info.json

{
    "info":
    {
        "users":
        [
            {
                "id":119476949,
                "name":"oauth_dancer",
                "dm":false
            }
        ],
        "delimited":"none",
        "include_followings_activity":false,
        "include_user_changes":false,
        "replies":"none",
        "with":"user"
    }
}

You may notice that, unlike the Site Streams control message, the “info request” does not include an array of the user_ids a user in your stream is following (AKA their “friends”). To obtain this data, you can use the control streams friends/ids method that behaves much like its REST API counterpart.

A control stream may not be ready for manipulation and querying directly after receiving the control event — it may take as much as a minute for a stream info request to fully reflect the users currently connected to the specified stream.

Add additional authenticated users to a Site Streams connection

URI format: POST /1.1/site/c/:stream_id/add_user.json

Adding a user to the current connection is as easy as sending a OAuth POST such as:

POST /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/add_user.json
POST body: user_id=819797

This would add user 819797 to the current stream if you had access tokens for them. If it were not possible to add the specified user(s) to the stream, you would get a 400 Bad Request HTTP code with the message: “No authorized followings found for your request”

Successful add requests will be returned an empty 200 OK response. The user(s) will be added to your specified stream and you’ll see the “preamble” for the added user(s) in your stream near immediately. You could also issue another GET request to the “info” endpoint to verify that the stream has changed.

The user_id parameter can be supplied with up to 100 user IDs, separated with commas. Monitor the number of connections in your stream with the info method to ensure they do not exceed the connection limit. Use remove_user to remove users from the stream to make room for new users.

Your initial connection to Site Streams allows you to specify 100 users. You can stream up to 1,000 users per connection, but you must add the additional 101st to 1,000th users through the add_user method, at a rate not exceeding 25 requests per second per site stream installation. This allows you to add around 2,500 users per second to your current pool of site streams connections.

Remove authenticated users from a Site Streams connection

URI format: POST /1.1/site/c/:stream_id/remove_user.json

Removing a user from the current connection is as easy as sending a OAuth POST such as:

POST /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/remove_user.json
POST body: user_id=819797

This would remove user 819797 to the current stream if you had access tokens for them and they were part of the stream. If it were not possible to remove the specified user(s) from the stream, you would get a 400 Bad Request HTTP code with the message: “No authorized followings found for your request”

Successful removal requests will be returned an empty 200 OK response. The user will be removed from your specified stream and you’ll see the “preamble” for the added users in your stream near immediately. You could also issue another GET request to the “info” endpoint to verify that the stream has changed.

Obtain information about the followings of specific users present on a Site Streams connection

URI format: POST /1.1/site/c/:stream_id/friends/ids.json

This method is much like GET friends / ids in the REST API, except the scope is limited to users on a specific stream. The list of followings/friends is definitive in that it’s what the Site Streams connection is aware of for the specified user. Use cursors in the same way as you would on the REST API equivalent.

POST /1.1/site/c/1_1_54e345d655ee3e8df359ac033648530bfbe26c5f/friends/ids.json
POST body: user_id=119476949

{
    "follow":
    {
        "user":
        {
            "id":119476949,
            "name":"oauth_dancer",
            "dm":false
        },
        "friends":
        [
            795649,
            819797,
            1401881,
            3191321,
            6253282,
            8285392,
            9160152,
            13058772,
            15147442,
            15266205,
            15822993,
            27831060,
            101058399,
            289788076
        ],
        "previous_cursor":0,
        "next_cursor":0
    }
}

Recent changes to this document:

• Sept 2011: Updated to 1.1.
• Oct 2011: Base control URI now includes “:stream_id/info.json” as part of the path. All other resources now include “.json” in the path.
• Nov 2011: “:stream_id/info.json” no longer includes friendship information, use “:stream_id/friends/ids.json” instead. Can now add up to 1,000 users per stream using “:stream_id/add_user.json”
• Jan 2012: Releasing documentation to all Site Streams developers. Thanks to our beta testers! Clarification on connection limits.