BuzzStream API v1.0

This is the documentation for the v1.0 read and write Buzzstream API. If you have additional questions, or believe you have encountered a bug, don't hesitate to contact customer support.

General

All API responses are JSON. Responses for GET requests on resources which could potentially yield multiple results are wrapped in a Paginator object. GET requests for subresources that yield multiple results are returned as a simple list. All requests to the BuzzStream API must be authenticated. In order to authenticate you must have access to a BuzzStream account.

OAuth

The BuzzStream API supports authentication via OAuth v1.0a. Both 2-legged and 3-legged workflows are supported.

2-Legged Authentication

The most common use case will be authenticating via the OAuth 2-legged authentication process which requires requests be signed using the consumer key and consumer secret. You can obtain these by logging in to your BuzzStream Account.

PHP Example

   
   # OAuth library available at https://code.google.com/archive/p/oauth-php/downloads
   # Make the following modifications:
   # OAuthRequest.php change line 187 from:
   if ($token_type != 'requestToken')
   # to
   if ($token_type != 'requestToken' && !empty($this->param['oauth_token']))

   # OAuthRequestSigner.php change line 131 from:
   if ($token_type != 'requestToken')
   # to
   if ($token_type != 'requestToken' && !empty($token))

   # Example taken from example/client/twolegged.php
   include_once "../../library/OAuthStore.php";
   include_once "../../library/OAuthRequester.php";

   // Test of the OAuthStore2Leg

   $key = '??????'; // fill with your public key
   $secret = '??????'; // fill with your secret key
   $url = "https://api.buzzstream.com/v1/"; // fill with the url for the oauth service

   $options = array('consumer_key' => $key, 'consumer_secret' => $secret);
   OAuthStore::instance("2Leg", $options);

   $method = "GET";
   $params = null;

   try
   {
        // Obtain a request object for the request we want to make
        $request = new OAuthRequester($url, $method, $params);

        // Sign the request, perform a curl request and return the results,
        // throws OAuthException2 exception on an error
        // $result is an array of the form: array ('code'=>int, 'headers'=>array(), 'body'=>string)
        $result = $request->doRequest();

        $response = $result['body'];
        var_dump($response);
   }
   catch(OAuthException2 $e)
   {
        echo "Exception";
   }

Ruby Example


require 'oauth'
require 'json'

consumer_key="????"
consumer_secret="????"
base_url="https://api.buzzstream.com"

#Create a consumer for the buzzstream api
consumer = OAuth::Consumer.new(consumer_key, consumer_secret,
                :site => base_url,
                :http_method => :get)

#From the consumer create an access token for 2leg authentication
access_token = OAuth::AccessToken.new consumer

#Perform request
response = access_token.get("/v1")

#Print response
json_response = JSON.parse(response.body)
for value in json_response
        puts value
end

3-Legged Authentication

The 3-Legged authentication process is meant to provide 3rd parties integrating with the BuzzStream API a way to authenticate on the behalf of BuzzStream users, once they have granted permission, without requiring them to provide a password or API key. This process is described here. Note that 3-Legged Authentication is not needed if you are only integrating with your own account. In that scenario, 2-legged authentication should be used. If you are writing a 3rd party integration for BuzzStream then please contact support, as this option is not enabled by default.

OAuth Resources to retrieve tokens are provided by the BuzzStream API server. Authorization resources are managed by the BuzzStream Webapp server. In step one of the 3-legged process, your client will make an HTTP POST call to https://api.buzzstream.com/requestToken. Your POST request should contain an Authorization request header with OAuth parameters that look something like this: 
                
    OAuth
        oauth_callback="http://your_login_callback_url",
        oauth_nonce="9903035",
        oauth_signature_method="HMAC-SHA1",
        oauth_timestamp="1402681079",
        oauth_version="1.0",
        oauth_consumer_key="<your_consumer_key>",
        oauth_signature="1Z514mdm0uQXlnUYpqURxPoHPlQ%3D"
oauth_callback is a url provided by the client that the BuzzStream Webapp server can redirect the user to, after he/she logs in to BuzzStream and grants access to the client to access his/her data. oauth_nonce is a random number that your client will generate. oauth_signature_method will be HMAC-SHA1 for our purposes. As implied, you will need an hmac library that you can use to sign your requests. oauth_timestamp is a unix-time timestamp that is generated by your client. oauth_version will be 1.0 -- we do not support oauth 2.0. oauth_consumer_key is the key that is found in your 3rd party integrator BuzzStream account (this is a special account that is separate from your normal group account that is created for you by BuzzStream Customer Service). This key can be distributed if you intend to distribute a client to your customers. oauth_signature is a cryptographic hash that your client will have to compute using an hmac library, the aforementioned oauth parameters, and your consumer key. A javascript example is available here.

A 200 response to the above call will look something like this: 
                
    oauth_callback_confirmed=true
    &oauth_token=f9cb406e-2c2d-4065-8f40-033783aa5776
    &oauth_token_secret=yv4prt7Ia%2FefIjhWWiokkjr1QHlD6upO%2FACYWDyCgKiO1f3UXmA9n5MRkg8UCae35rZh5mlc0ODdsG813A7G0Iiuv%2BFduLscNqQ%2B7EVqtJA%3D
The response indicates success or failure (which should already be evident from the http response code), and will contain an oauth token and oauth token secret.

The next step is for the user to get authorized (login to buzzstream) and grant access to the consumer. This is done by making a call to the BuzzStream webapp server (with the oauth_token received in the previous step as a query parameter). The authorization resource is located at https://app.buzzstream.com/oauth_verification

HTTP GET call with the oauth_token returned in step one above might look something like this: 
                
    https://app.buzzstream.com/oauth_verification%252FrequestToken%252Ff9cb406e-2c2d-4065-8f40-033783aa5776
At this point the BuzzStream Webapp server will redirect the client to login. Upon successful login, the client will be redirected to a grant screen, also provided by the BuzzStream Webapp server. This will provide the user with the option to grant or deny access to the 3rd party requesting it. If the user grants access, the server will redirect the user back to the consumer using the oauth_callback url provided by the consumer. The verifier needed to obtain an access token will be found in the callback url as a query parameter. For example: 
                
    http://your_login_callback_url?verifier=iz1sFm
The final step of this process is to obtain an access token. This is done by making an HTTP POST call to https://api.buzzstream.com/accessToken.

An OAuth Authorization header is again included with a similar set of params as in the first step. This time it will look something like: 
                
    OAuth
        oauth_nonce="234230634",
        oauth_signature_method="HMAC-SHA1",
        oauth_timestamp="1402701000",
        oauth_version="1.0",
        oauth_consumer_key="<your_consumer_key>",
        oauth_verifier="iz1sFm"
        oauth_signature="I7SxzPTYezfaN%2BaENdo5R5ZMIzU%3D"
Notice that oauth_callback is no longer needed. oauth_nonce, oauth_timestamp, and oauth_signature are all recomputed. oauth_verifier is now included as a parameter (and used in computing the signature of course).

A 200 response looks like this: 
                
    oauth_token=46f256ab-11d6-4213-b16b-c3eafa189026
    &oauth_token_secret=PahdGcTgqOJ8rivT9K4%2Fnx%2FQgZf9GJiRjhhjJ2kPdwk6QRXsd%2B6IEzdw%2BdR%2BSWDSBF7taKxE6F6vdNZzXoWUDbgtrdwZys41KAHGjMZ7F%2FQ%3D
The response contains a token and secret that can now be presented by the client in order to access the authorized User's resources on our API server.

Tokens

/accessToken
POST to retrieve an OAuth Access Token

/requestToken
POST to retrieve an OAuth Request Token

Rate Limiting

Rate limits in version 1 of the BuzzStream API are applicable on a per-user basis. Each User is permitted to make a maximum of 5 API calls per second. Subsequent calls made within the same 1 second window will be suspended in 2 second intervals until the user's call rate falls below the 5 calls per second threshold. So, for example, if a user makes 11 concurrent calls, Buzzstream will attempt to respond to 5 of them immediately, another 5 of them after 2 seconds have passed since they were received, and the final request after 4 seconds have passed since the request was received.

BuzzStream Data Resources