Api Overview

The Sprocket API was built to provide third-party applications access to perform actions on behalf of a Rallybound platform User.

Authentication

The Sprocket API uses OAuth 2.0 3-legged to allow third-party Clients to access users campaign data. the Sprocket API follows the OAuth 2.0 Authorization Framework specifications.

Request Format

The Sprocket API follows the HTTP REST protocol.

HTTP Method

URI

The URI of an individual API method may contain dynamic parameters (surrounded by curly brackets). they will need to be populated with their respective values, to generate the final URI.

Request Parameters

Request parameters for each API method will be listed in the following table format:

Required parameters that are absent, or parameters that are of incorrect data type (such as passing abc for a parameter that has a data type of int will generate a 400 Bad Request error)

Request Authorization

Most of the Sprocket API Methods will require authorization. There are two types of authorizations listed below. Each of the API methods will list the type of authorization required.

We recommend that the Client application make use of the Authorization HTTP header, although we plan to support an alternative that makes use of request parameters.

POST /sprocket/v2/test/me HTTP/1.1
    Host: rest.rallybound.com    Authorization: Bearer NBFHLSJ7w8URN9jJVLtmLmuS-e85Ya64hmUDf_aar4AfQNEEN4

string endpoint = "https://rest.rallybound.com/sprocket/v2/test/me";
    string accessToken = "NBFHLSJ7w8URN9jJVLtmLmuS-e85Ya64hmUDf_aar4AfQNEEN4";
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(endpoint);
    request.Headers.Add(HttpRequestHeader.Authorization, "Bearer " + accessToken);
    

POST /sprocket/auth/oauth2/token HTTP/1.1
    Host: rest.rallybound.com    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

string endpoint = "https://rest.rallybound.com/sprocket/auth/oauth2/token";
    string client_id = "s6BhdRkqt3";
    string client_secret = "gX1fBat3bV";
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(endpoint);
    request.Credentials = new NetworkCredential(client_id, client_secret);
    

Content Type

The Sprocket API is designed for JSON payloads, but it supports XML payloads as well. To send a request in XML, set the request Content-Type header to application/xml or text/xml.

Note that empty XML tags are treated as null JSON values not empty objects ({})

Response Format

Status Code

The Sprocket API will respond to each call with a HTTP status code to indicate if the call was successful. Status codes of 2xx indicate success, 4xx indicate client errors (such as missing request parameters) while 5xx indicate server errors.

Content Type

The Sprocket API will respond in JSON, but it supports XML as well. To get a response in XML, set the request Accept header to application/xml.

Pretty Print

To get a prettified response, add a pretty query parameter set to true.

POST /Example HTTP/1.1
Host: rest.rallybound.com

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "Key1": "Value1",
  "Key2": 1234
}

POST /Example HTTP/1.1
Host: rest.rallybound.comAccept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

<response>
  <Key1>Value1</Key1>
  <Key2>1234</<Key2>
<response>

Pagination

Requests for collections can return between 0 and 100 results, controlled using the limit query parameter. All collection endpoints are limited to 10 results by default.

Retrieving records past the limit is done by using the offset query parameter.

This example would fetch teams 101 through 150
GET /sprocket/v2/admin/campaigns/1234/teams?limit=50&offset=100

A collection's range can be set to start from a specified result by adding the from_id or starting query parameters.

The from_id parameter (integer) will skip all records with their primary id less than the specified integer.

The starting parameter (long) will skip all records created prior to the specified unix timestamp.

If the request is made to a modified endpoint, the starting parameter will skip all records last modified prior to the specified unix timestamp (based on the Last_Modified_On timestamp).

Endpoints which support pagination will define their fields parameters in their documentation.

Filtering

Collections may be limited based on specified criteria. This is done by passing filters as query parameters for fields within an object. The parameter specifies the field by which to filter, and its value determines the criteria by which to filter.

Filters may be passed for fields anywhere in an object structure (assuming filtering is supported by the relevant field). So, for example, a donation object can be filtered by donation.amount or donation.payment.currency_key (or both).

Collections may be filtered by string for string fields; by relational operators for integer, decimal, and long fields (including timestamps); and by logic (true/false) for boolean fields.

Strings are filtered based on the exact value passed. To filter based on a partial string, wildcards may be used by prepending or appending an asterisk ("*") to the value passed.

The following example would limit the returned collection to teams whose names start with "our":
GET /sprocket/v2/admin/campaigns/1234/teams?team.name=our*

Integers may be filtered by the relational operators equals ("="), greater than (">"), or less than ("<"). When filtering by greater or less than, the equals sign sets the value of the parameter, and is not part of the relational operator. When filtering by equality, a single equals sign is used, which sets the parameter value, and also checks for equality.

The following example would limit the returned collection to donations which are greater than $100:
GET /sprocket/v2/admin/campaigns/1234/donations?donation.amount=>100

The following example would limit the returned collection to donations which are equal to $250:
GET /sprocket/v2/admin/campaigns/1234/donations?donation.amount=250

Endpoints which support filtering will indicate their respective filterable fields in their documentation.

Sorting

Collections may be sorted by specified fields using the sort query parameter. To sort by multiple fields, the fields should be passed comma-delimited. The order of the fields will determine the priority of the sort.

By default, the sort order is ascending. To sort descending, preface the relevant field with "-".

The following example would return teams in order of amount raised, with top raised listed first:
GET /sprocket/v2/admin/campaigns/1234/teams?sort=-team.amount_raised

Endpoints which support sorting will indicate their respective sortable fields in their documentation.

Batch

Some create (POST) and update (PUT) endpoints support batches.This is done by including multiple records in the payload, see below for example.

The response will include counts for successfully processed records and errors, respectively, and list out each record with relevant information in a Results array. Successful records will return a status code of 200 and the record's ID (see below), while errors will return an error status code, such as 400, along with information regarding the error.

By default, successful records will return only their ID. It is possible to return the entire object by setting batch_respond_with_complete_objects (under setting) to true in the initial payload. We recommend only doing this if the response objects are needed.

Here is an example:

PUT /admin/campaigns/{campaign_id}/donations HTTP/1.1
Host: rest.rallybound.com                                            
{
   donations: [
       {
           id: 22355,
           amount: 200
       },
       {
           id: 22356,
           amount: 200
       }
   ]
}

HTTP/1.1 200 OK
{
  "Success_Count": 1,
  "Error_Count": 1,
  "Results": [
      {
          "Status": 200,
          "Body": 22355
      },
      {
          "Status": 400,
          "Body": "Donation.Id: No Donation with passed ID"
      }
  ]
}

PUT /admin/campaigns/{campaign_id}/donations HTTP/1.1
Host: rest.rallybound.comAccept: application/xml
                                            
<donations>
    <element>
        <id>22355</id>
        <amount>200</amount>
    </element>
    <element>
        <id>22356</id>
        <amount>200</amount>
    </element>
</donations>

HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8

<response>
   <Success_Count>1</Success_Count>
   <Error_Count>1</Error_Count>
   <Results>
      <element>
         <Status>200</Status>
         <Body>22355</Body>
      </element>
      <element>
         <Status>400</Status>
         <Body>Donation.Id: No Donation with passed ID</Body>
      </element>
   </Results>
</response>

Authorization Endpoints

Access Tokens

In order to make authorized calls to the Sprocket API methods, your application must first obtain an Access Token on behalf of a User. Once a valid Access Token is obtained, it can be used to perform multiple API methods until the token expires.

Obtaining Access Tokens

Request Parameters:

https://rest.rallybound.com/sprocket/auth/oauth2/authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Foauthoauth2%2Fclient_redirect

string endpointBase = "https://rest.rallybound.com/sprocket/auth/oauth2/authorize";
string client_id = "s6BhdRkqt3";
string redirectUri = System.Web.VirtualPathUtility.ToAbsolute("~/oauthoauth2/client_redirect");
string state = "abc";

string constructedUri = string.Format("{0}?response_type=code&client_id={1}&redirect_uri={2}&state={3}",
    endpointBase, client_id, Uri.EscapeDataString(redirectUri), Uri.EscapeDataString(state));

/*ASP.NET classic*/
Response.Redirect(constructedUri);

/*ASP.NET MVC*/
return Redirect(constructedUri);

Redirection Parameters

Following the OAuth 2.0 spec, once the User grants access to your application they will be redirected to the redirect_uri specified in the authorization request. The following redirect parameters will be appended:

https://client.example.com/oauthoauth2/client_redirect?code=s6BhdRkqt3&state=xyz

Exchanging the Nonce for Access & Refresh Tokens

Nonce codes are valid for 10 minutes, and are to be exchanged for a pair of Access and Refresh tokens. Keep in mind that an individual nonce code can only be used once, so if there is an error during the exchange - you will need to begin a new Authorization Flow.

To exchange the code received via the redirect parameter for an Access Token and a Refresh Token, issue a request to the Token Endpoint using the client_secret authorization method, along with the request parameters below:

Request Parameters:

POST /sprocket/auth/oauth2/token HTTP/1.1
Host: rest.rallybound.comAuthorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Foauthoauth2%2Fclient_redirect

string endpoint = "https://rest.rallybound.com/sprocket/auth/oauth2/token";
string client_id = "s6BhdRkqt3";
string client_secret = "gX1fBat3bV";

//redirect_uri used in the authorization request
string redirectUri = "https://client.example.com/oauthoauth2/client_redirect";

//code issued as redirect parameter
string code = "SplxlOBeZQQYbYS6WxSbIA";


HttpWebRequest request = (HttpWebRequest)WebRequest.Create(endpoint);
request.Credentials = new NetworkCredential(client_id, client_secret);
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
using(Stream requestStream = request.GetRequestStream())
using(StreamWriter writer = new StreamWriter(requestStream))
{
    writer.Write(string.Format("grant_type=authorization_code&code={0}&redirect_uri={1}",
        Uri.EscapeDataString(code), Uri.EscapeDataString(redirectUri));
}
using(HttpWebResponse response = (HttpWebResponse)request.GetResponse())
{
    //....
}

Response Parameters:

POST /sprocket/auth/oauth2/token HTTP/1.1
Host: rest.rallybound.comAuthorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Foauthoauth2%2Fclient_redirect

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "6vnJ8CL_gttCtAdwXcHrKmK6SgCjfdX-LSpTvkw5576cETLABWLGdgKzrGrtm4pxa-ubrnmHNVw",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "7Naj7aZfSQvEzUa2MvezDk53"
}

POST /sprocket/auth/oauth2/token HTTP/1.1
Host: rest.rallybound.comAccept: application/xml
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Foauthoauth2%2Fclient_redirect

HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

<response>
  <access_token>6vnJ8CL_gttCtAdwXcHrKmK6SgCjfdX-LSpTvkw5576cETLABWLGdgKzrGrtm4pxa-ubrnmHNVw</Key1>
  <token_type>Bearer</Key1>
  <expires_in>1800</Key1>
  <refresh_token>7Naj7aZfSQvEzUa2MvezDk53</Key1>
<response>

Using Access Tokens

Now that the User granted access to your application, you may use the Access Token to perform actions on their behalf. Most of the Sprocket API methods require AccessToken authorization.

Token Expiry

Access Tokens expire 30 minutes after they was issued.

Refresh Tokens

Once a Access Token expires, use the Refresh Token to obtain a fresh one without requiring a new Authorization Flow, as demonstrated below:

                    

+--------+                                           +---------------+
|        |--(A)------- Authorization Grant --------->|               |
|        |                                           |               |
|        |<-(B)----------- Access Token -------------|               |
|        |               & Refresh Token             |               |
|        |                                           |               |
|        |                            +----------+   |               |
|        |--(C)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
|        |<-(D)- Protected Resource --| Resource |   | Authorization |
| Client |                            |  Server  |   |     Server    |
|        |--(E)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
|        |<-(F)- Invalid Token Error -|          |   |               |
|        |                            +----------+   |               |
|        |                                           |               |
|        |--(G)----------- Refresh Token ----------->|               |
|        |                                           |               |
|        |<-(H)----------- Access Token -------------|               |
+--------+                                           +---------------+

                

Token Expiry

By default, Refresh Token expire 1 year after it was issued.