Usage
Lifecycle
The API will always return a JSON response (even for errors). Each request should consist of the desired API method, any parameters, your unique API key and a request hash.
Although all curriculum elements are versioned, only 'approved' versions are available via this API. The unique identifier included with query results is tied to the entire history of a given object, rather than a specific version. This means that an object ID will always stay the same, regardless of any changes or new versions.
Authentication
Our API requires that your API key be included in each request, as well as an HMAC-SHA1 hash. This hash is generated from the method path and query string, using your API secret as the key.
The following rules apply:
- The API key should be included using the api_key parameter.
- The hash should be performed on the URL path and query string only. No parameter re-ordering is necessary.
- The hash should be appended to the end of the URL, using the hash parameter.
A hash generator is included in the playground.
Example request:
| API Key | b1215747-ab55-4d83-8b49-9f072f085683 |
|---|---|
| API Secret | d4bea8034b51 |
| Method to call | /api/query/123?date=today |
| ...add API key | /api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683 |
| ...hash using secret | 404085eb7c45ced17705b9b77d4fb95c8e480f60 |
| ...append as parameter | /api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683&hash=404085eb7c45ced17705b9b77d4fb95c8e480f60 |
| ...add host | https://website.com/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683&hash=404085eb7c45ced17705b9b77d4fb95c8e480f60 |
C#
// Method with API key string query = "/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683"; // API secret string secret = "d4bea8034b51"; // Hash byte[] queryBytes = Encoding.ASCII.GetBytes(query); byte[] secretBytes = Encoding.ASCII.GetBytes(secret); byte[] hashBytes = (new HMACSHA1(secretBytes)).ComputeHash(queryBytes); string hash = BitConverter.ToString(hashBytes).Replace("-", "").ToLower(); // hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"
Java
// NB Example uses Apache Commons Codec import org.apache.commons.codec.digest.HmacUtils; // Method with API key String query = "/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683"; // API secret String secret = "d4bea8034b51"; // Hash String hash = HmacUtils.hmacSha1Hex(secret.getBytes(), query.getBytes()); // hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"
JavaScript
// NB Example uses CryptoJS // Method with API key var query = "/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683"; // API secret var secret = "d4bea8034b51"; // Hash var hash = CryptoJS.HmacSHA1(query, secret).toString(); // hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"
PHP
// Method with API key $query = '/api/query/123?date=today&api_key=b1215747-ab55-4d83-8b49-9f072f085683'; // API secret $secret = 'd4bea8034b51'; // Hash $hash = hash_hmac('sha1', $query, $secret); // $hash == "404085eb7c45ced17705b9b77d4fb95c8e480f60"
Errors
Our API uses conventional HTTP response codes to indicate the success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error resulting from the provided information (e.g. a required parameter was missing, an incorrect key/hash) and codes in the 5xx range indicate an error on our server.
See the object definition for more details.