Overview

This describes the resources that make up the official version 2 of the Social Gateway API. If you have any problems or requests please contact Support.

Current Version
Schema
Security
Client Errors
Response Schema
HTTP Verbs
Authentication

Current Version

All API access is done through the http://yourdomain/api/v2/ base url. If you are not sure about which domain you should use, please contact Support

All requests to the Social Gateway API receive the v2 version of the API. You must explicitly request this version via the /api/v2/ prefix in the url.

http://yourdomain/api/v2/

Schema

When invoking this API, all arguments should be passed as plain http parameters. The API will return all data in JSON format, in the body of the http response.

$ curl -i -X GET "http://yourdomain/api/v2/me"

HTTP/1.1 200 OK
Server: nginx/1.2.3
Date: Thu, 17 Jul 2014 15:36:17 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive

{
	"success": true,
	"statusMessage": "you are not logged in",
	"logged_in": false
}

All dates are specified in standard full date and time format: yyyy-MM-ddTHH:mm:ssZ using your domain’s configured timezone

...
"date" : "2015-02-20T16:32:51-0300",
 ...

Security

Every call to the api should include the access_token parameter, except for calls to the /authenticate endpoint, which is the one you must use to obtain a valid access_token.

$ curl -i -X GET https://yourdomain/api/v2/campaign/stats?access_token=77cd11b71335b73d9a518ec52ee4590fe88b6540

See the /authenticate api endpoint to learn how to obtaining a valid access token.

Client Errors

When calling this API, you must check the HTTP status code returned by Social Gateway in order to see if there was an error in your call. These are common error scenarios:

Sending requests without an access token will result in a 401 response

 HTTP/1.1 401 Please include the access_token parameter in your requests. You can obtain one using the /api/v2/authenticate endpoint

Sending requests with an invalid/expired access token will result in a 401 response
```
 HTTP/1.1 401 Please renew your access_token
```
All other kind of invalid requests will return a 400 Bad Request or 404 Not Found response.
```
 HTTP/1.1 400 Bad Request
 HTTP/1.1 404 Not Found
```

Response Schema

All well-formatted and authenticated requests get a 200 OK response. That means that the request was processed by Social Gateway’s API. The response is sent back as a JSON structure in the body of the response. For simple GET request, normally you will get a JSON Object or Array with the requested data. For POST request, responses will be a JSON Object that always contain at least these two attributes: success and statusMessage. If success is false, then you can see the error message in the statusMessage attribute of the response.

$ curl -i -X GET "http://yourdomain/api/v2/me?access_token=ACCESS-TOKEN"

HTTP/1.1 200 OK
Server: nginx/1.2.3
Date: Thu, 17 Jul 2014 16:07:27 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive

{
    "success": true,
    "statusMessage": "you are logged in as 'api'",
    "logged_in": true
}

HTTP Verbs

Where possible, API v2 strives to use appropriate HTTP verbs for each action.

Verb	Description
`HEAD`	Can be issued against any resource to get just the HTTP header info.
`GET`	Used for retrieving resources.
`POST`	Used for creating or updating resources, or perform custom actions.
`PUT`	Used for replacing resources or collections.
`DELETE`	Used for deleting resources.

Authentication

Requests that require authentication will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of private schemas to unauthorized users.

Obtaining an Access Token

To obtain an access token, you need to call the authenticate endpoint, as shown in the example below. For that call, you need a valid apiKey, userName and password. This information should be provided to you by your Social Gateway support representative or account manager.

$ curl -i -X POST -d 'userName=YOUR-USER-NAME&apiKey=YOUR-API-KEY&password=YOUR-PASSWORD'  http://yourdomain/api/v2/authenticate

HTTP/1.1 200 OK
Server: nginx/1.2.3
Date: Sat, 18 Jul 2014 00:19:29 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Expires: Thu, 01-Jan-1970 00:00:00 GMT

{
	"success": true,
	"access_token": "202060259b0df2b6d5b56a9b50a149e3270816f2",
	"expires": "2015-02-20T16:32:51-0300"
}

Using the Access Token

The call to the authenticate endpoint returns JSON object with a access_token attribute, which you can then use in subsequent calls to the API, by adding the access_token parameter to every call.

$ curl -i -X GET https://yourdomain/api/v2/me?access_token=ACCESS-TOKEN

Refreshing the Access Token

If at anytime you get a HTTP/1.1 401 Please renew your access_token response, you should renew your access token by calling the authenticate endpoint again.

API