Developer Center

SocialAdr API Documentation

Table of Contents

Overview

Authentication

RESTful API style

Request Parameters and Encoding

Responses

Keep in mind

Sign up for Developer Program

Create an App

Start Developing

Get the necessary IDs

Authorization Page

Making API Calls

Refreshing Access Tokens

Overview

The SocialAdr API gives you, as a developer, the ability to create web or mobile applications that use the SocialAdr platform.  

Authentication

OAuth 2.0 is used:  http://oauth.net/2/

More details about this process are described under Authorization Page.

OAuth Process Diagram

RESTful API style

The API attempts to embrace the RESTful design principles.

Each api method URL corresponds to a resource. The HTTP method (aka. verb) is used to specify the operation. A GET request is used to retreive data. A POST request may add, update or destroy data. The DELETE method is also accepted for methods that destroy data. API methods usually require particular HTTP methods. Such requirements are documented for each method.

Request Parameters and Encoding

The API only accepts and returns text encoded in UTF-8.

The API uses standard HTTP query string to pass parameters. Parameters are required to be properly URL encoded.

Responses

The API attempts to returns meaningful HTTP status codes for each request. Possible codes are:

  1. 200 OK: Success!
  2. 400 Bad Request: Some request parameters are invalid or the API rate limit is exceeded.
  3. 401 Not Authorized: Authentication credentials are missing or invalid.
  4. 403 Forbidden: The request has been refused because of the lack of proper permission.
  5. 404 Not Found: Either you're requesting an invalid URI or the resource in question doesn't exist (e.g. no such user).
  6. 500 Internal Server Error: Something is broken.
  7. 502 Bad Gateway: SocialAdr is down or being upgraded.
  8. 503 Service Unavailable: The SocialAdr servers are too busy to server your request. Please try again later.

The response body contains data in the JSON format - a light weight serialization format for structured data.

Keep in mind

  1. Please let us know if you are going to release software that uses this publicly, so that we can at least have a heads-up and hopefully test things out beforehand.
  2. Please wait at least one second between queries, or you are likely to get automatically throttled. If you are releasing a library to access the API, you MUST do this.
  3. Please watch for 400 errors and back-off appropriately. It likely means that you have been throttled.
  4. Please set your User-Agent to something identifiable. The default identifiers like “Java/1.4.3” or “lwp-perl” etc tend to get banned from time to time.
  5. If you are releasing software or a service for other people to use, your software or service MUST NOT add any bookmarks without a user’s explicit direction. Likewise, you MUST NOT modify any bookmarks except under the user’s explicit direction.

Sign up for Developer Program

Sign up for the developer program to gain access to the ability to create apps.

http://socialadr.com/pg/apps/developers

Create an App

Go to the Create App page:

http://socialadr.com/pg/apps/create

Fill out the form to apply for API access for your application. We will notify you when your application has been approved.  When creating an App, you’ll specify a “Redirect URI”, which is the URL of the landing page described in Authorization Page.

Start Developing

Get the necessary IDs

Once your app has been approved, you need to get its App ID, Client ID, and Client Secret.  These can by going to the Manage Apps page, then clicking the “Manage” button for your app.

Now you’re ready to connect to the SocialAdr API.

Authorization Page

Your first interaction with the SocialAdr API will be setting up an Authorization Page. The Authorization page is a page in your app that users are redirected to when they have authorized your app. When users are redirected to this page, we append a query string parameter with an Access Code.

If you have an Authorization Page URL of

http://www.yourapp.com/authorized.php

We will redirect users to

http://www.yourapp.com/authorized.php?code=USERSAUTHCODE

Once you have the user’s Authorization Code, you must exchange it for an Access Token by making an API call to the SocialAdr oauth grant method.

POST

http://socialadr.com/api/oauth/grant

Param

Description

grant_type

(string) This should always be set to ‘authorization_code’

code

(string) The user’s Authorization Code (just received)

client_id

(int) Your app’s Client ID

client_secret

(string) Your app’s Client Secret

redirect_uri

(string) URL of your app’s Authorize Page

scope

(string) space-separated string of app permissions.

Example: ‘basic url account’

Sample Response

{

"access_token":"f5bd382e55abe2f8b8d9a187e3cdc0b2bbc9c421",

"expires_in":3600,

"token_type":"bearer",

"scope":"basic url account",

"refresh_token":"9be1dae09bc57f9a33547352d7d8c07c20bd03ba"

}

Typically, you would now save the Access Token and Refresh Token in your app’s database, so that you can connect to the SocialAdr API, as this user, whenever needed.

Making API Calls

Using the Access Token you’ve just received and saved for this user, you can now make API calls to access their SocialAdr data.

The list and details of all API Methods is available here:

http://socialadr.com/pg/apps/api-methods

Refreshing Access Tokens

Access tokens expire after a set period of time (currently 1 hour). When you receive an Access Token, you should also be given a Refresh Token. You will want to save both. The Refresh Token is used to get a new Access Token when the old one has expired.

POST

http://socialadr.com/api/oauth/grant

Param

Description

grant_type

(string) This should always be set to ‘refresh_token’

refresh_token

(string) The user’s Refresh Token

client_id

(int) Your app’s Client ID

client_secret

(string) Your app’s Client Secret

redirect_uri

(string) URL of your app’s Authorize Page

scope

(string) space-separated string of app permissions.

Example: ‘basic url account’

Sample Response

{

"access_token":"f5bd382e55abe2f8b8d9a187e3cdc0b2bbc9c421",

"expires_in":3600,

"token_type":"bearer",

"scope":"basic url account",

"refresh_token":"9be1dae09bc57f9a33547352d7d8c07c20bd03ba"

}