StudyAbroad101 API Documentation
In order to use the API you need an API USER and an API KEY; Each resource can handle one or more of the following HTTP methods : GET, PUT, DELETE, POST.
There are several required HTTP headers :
- X-A101-Date - in RFC 2822 format - for example: Thu, 11 Jul 2013 14:23:08 +0000 (please see http://www.ietf.org/rfc/rfc2822.txt for details on this format) Note: the date / time must be GMT timezone based.
- X-A101-User - for example: studyabroad101_api_user
- X-A101-Auth - for example: of+LxjLsAGY4x0ob8sbGKVo2FiQ=
The value of XA101Auth header is used for authentication of the request. See below the way this header is constructed:
step 1 : signature_string = concatenate strings (HTTP verb , Query String , XA101User header value , X-A101-Date header value);
Note: Query String must have no starting “/”, and must be separated by a single “/” from the XA101User string.
E.g: if the request is GET /students/?filters[id]=1111, the signature_string will look like below:
GETstudents/?filters[id]=1111/XA101UserThu, 11 Jul 2013 14:23:08 +0000
(where instead of “XA101User” will be used the real API USER).
step 2 : XA101Auth header value = HMACSHA1 (API KEY, signature_string)
The HMACSHA1 algorithm is explained in detail here: http://en.wikipedia.org/wiki/HMAC#Implementation
Possible authentication errors
- AuthHeaderMissing - this means that the XA101Auth header was not detected in your request
- AuthTimeDifference - this means that the time difference between the request time and our server time is greater than allowed time Please read the important note below.
- ClientHeaderMissing - this means that the XA101Client header was not detected in your request
- DateHeaderMissing - this means that the Date header was not detected in your request
- InvalidClient - the supplied API USER is not registered with our system
- InvalidSignature - the supplied signature in X-A101-Auth header is wrong. Possible reasons are: the signature_string was not properly computed, the HMAC algorithm was not properly calculated, the API KEY is wrong or not valid
Important: because the signature string relies on a timestamp it is very important to have your server/system
time synchronized with a NTP server.
The web service allows 60 seconds time differences between the request date and server date.