|
|
Developer Center
SocialAdr API Documentation
Table of Contents
Request Parameters and Encoding
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:
- 200 OK: Success!
- 400 Bad Request: Some request parameters are invalid or the API rate limit is exceeded.
- 401 Not Authorized: Authentication credentials are missing or invalid.
- 403 Forbidden: The request has been refused because of the lack of proper permission.
- 404 Not Found: Either you're requesting an invalid URI or the resource in question doesn't exist (e.g. no such user).
- 500 Internal Server Error: Something is broken.
- 502 Bad Gateway: SocialAdr is down or being upgraded.
- 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
- 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.
- 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.
- Please watch for 400 errors and back-off appropriately. It likely means that you have been throttled.
- 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.
- 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.
https://socialadr.com/pg/apps/developers
Create an App
Go to the Create App page:
https://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.
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:
https://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.
|
Sample Response
|
