-
Notifications
You must be signed in to change notification settings - Fork 1
Home
Travis McHattie edited this page Nov 21, 2013
·
5 revisions
All API requests require authentication. There are 2 steps required to authenticate.
Step 1 is to request an access token Step 2 is to use this access token in future requests.
If no, or invalid authentication information is provided then an error message will be returned with status code 401:
{
"message": "401 Unauthorized"
}The below request will generate a successful token in the vagrant development environment.
curl http://localhost:8080/token \
-H "Accept: application/json" \
-H "Accept-Language: en_US" \
-u "apitestuser:TestPassword"
NodeJS sample code to generate a token
request(url)
.get('/token')
.set('Accept', 'application/json')
.set('Accept-Language', 'en_US')
.set('authorization', new Buffer('apitestuser:TestPassword').toString('base64'))
.end(function(err, res) {
if (err) { throw err; }
res.status.should.equal(200);
done();
});Successful access token response
{
"access_token":"9c55f367-557b-4ddb-ad90-3957fbec474d",
"token_type":"Token"
}- Authorization: When requesting an access token, send the value as the HTTP Basic Authentication credentials using your client_id and secret. You can specify them as -u "client_id:secret" they should be base64 encoded in your application but if you are using curl for testing you can leave it in plain text. When calling APIs, send the value as the OAuth 2.0 access token with the authentication type set as Token (Example: Authorization: Token {AccessToken}).
- Accept: Set to application/json.
- (optional) X-HTTP-Method-Override: If you do not want to use actual HTTP methods like "put" or "delete" then you can use this header to override the methods.
- (optional) X-API-VERSION If you want to use a specific API version then this header should be included. Right now the version is 1.0. Any changes introduced that could break 1.0 will be moved into a new version.
The API is designed to return different status codes according to context and action. In this way if a request results in an error the caller is able to get insight into what went wrong. The following list gives an overview of how the API functions generally behave.
- GET requests access one or more resources and return the result as JSON
- POST requests return 201 Created if the resource is successfully created and return the newly created resource as JSON
- GET, PUT and DELETE return 200 Ok if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
- DELETE requests are designed to be idempotent, meaning a request a resource still returns 200 Ok even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not. The following list shows the possible return codes for API requests.
- 200 Ok - The GET, PUT or DELETE request was successful, the resource(s) itself is returned as JSON
- 400 Bad Request - The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
- 401 Unauthorized - The request requires user authentication. The response MUST include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The client MAY repeat the request with a suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials.
- 403 Forbidden - The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.
- 404 Not Found - The server has not found anything matching the Request-URI. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.
- 405 Method Not Allowed - The request is not supported
- 408 Request Timeout - The client did not produce a request within the time that the server was prepared to wait.
- 500 Server Error - While handling the request something went wrong on the server side
- 503 Service Unavailable: The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
When listing resources you can pass the following parameters:
skip (default: 0) - number of records to skip limit (default: 20, max: no max) - number of items to list per query
- NodeJS * Current
- PHP - Coming Soon
- Ruby - Coming Soon
- Python - Coming Soon
- C# - Coming Soon