Open Data at Cardiff Unversity

Welcome to Open Data at Cardiff Unversity! A set of self-serve tools that developers can use to manage their access to Cardiff University APIs, as well as to create and manage their applications.

The APIs for Cardiff University are open and provide a simple interface to data. The APIs have been designed using RESTful methodology so that integration with other systems is as easy as possible.

Getting Started

Integrating with nearly all of our APIs requires the creation of an application and the generation of consumer keys and access tokens. Sign in with a University account to create an application and generate authentication tokens.

External Developers
To get a developer account, please send an email to:
integration@cardiff.ac.uk

Please note: When applying, please submit use case information about your intended use of our APIs.

Authentication

Example CURL command to retrieve a bearer token:

            
curl -k -d "grant_type=client_credentials"
-H "Authorization: Basic 123456789, Content-Type: application/x-www-form-urlencoded"
https://api.data.cardiff.ac.uk/token
            
        

The above command returns JSON structured like this:

            
{
    "access_token":"mybearertoken12345",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"myrefreshtoken12345",
    "scope":"default"
}
            
        

You can then use the acess token in the following way:

            
curl -X GET "https://api.data.cardiff.ac.uk/courses/v1/{COURSECODE}"
-H "Authorization: Bearer mybearertoken12345"
            
        

Make sure to replace mybearertoken12345 with your API key.

All our endpoints use OAuth2 to provide authorized access to the API.

The one thing to keep in mind is that all requests to the API must be made over SSL (https:// not http://).

To use this method, you need to use a bearer token. You can generate a bearer token by passing your consumer key and secret to the POST oauth2 / token endpoints.

Once you have a bearer token it must be included in all API requests to the server in a header that looks like the following:

Authorization: mybearertoken12345

Rate Limiting

In order to prevent abuse the API implements a number of throttles.

Throttle policies defined at a subscription level and are applied based on the subscription details of an API and the application details. These policies will limit the total number of requests that can go through from an application to a single API.

The default throttling tiers are as follows:

  • Bronze: 1000 requests per minute
  • Silver: 2000 requests per minute
  • Gold: 5000 requests per minute
  • Unlimited: Allows unlimited access

Structure

Example Envelope:

            
{
    "meta": {
        "count": 1,
        "code": 200,
        "contentType": "application/json",
        "errorStatus": false
    },
    "data": {
        ...
    }
}
            
        

The Envelope
Every response is contained by an envelope. Every response contains the following objects with which you can expect to interact:

If something should go wrong, you may see a response like:

            
{
    "meta": {
        "count": 0,
        "code": 400,
        "contentType": "application/json",
        "errorStatus": true,
        "errorMessage": {
            "code": 1000410,
            "message": "Error Message goes here"
        }
    },
    "data": {
        ...
    }
}
            
        

Meta The meta object is used to show extra information about the response to the developer. If all is well, you should see a code value of 200 and error status of false.

Data The data objects holds the actual data response. It may be an array or an object, but what ever it is this is where you'll find it.

JSONP

The following url:

            
https://api.data.cardiff.ac.uk/courses/v1/CRSCODE?callback=myfunction
            
        

Would return the follwoing:

            
myfunction({
    ...
});
            
        

JSONP is easiest explained with an example. Here's one from StackOverflow. If you need to receive your API response wrapped inside a JSONP callback function, you can use the callback query parameter with any valid API route. The data will be returned wrapped in the callback function you specify.

The callback value can be any valid JavaScript method name.

The entire JSON API response will be delivered wrapped in the requested callback function.