/
Getting Started - OpenAPI

These pages are WIP as we transition, update, and publish more documentation.

Getting Started - OpenAPI

tl;dr

All API requests need an API key. You can get an API key from using the API itself and confirming your email. Include the key in all requests as an X-API-KEY header. The live Swagger documentation is available here (https://openapi.data.uwaterloo.ca/api-docs/). There is a request per key limit, we’re experimenting with an implementation that’s usable but sustainable for consumed resources; currently you’ll get a 429 status code response if you exceed the per minute request allocation.

 

Getting an API key

 

  1. You'll need to get an API key to use for all your interactions with the Open Data API. You can get a key by using the Account endpoint (/v3/account).

  2. POST your valid email address, project name and description, and project URL (such as to the website, app store, etc.) to the Register method (/v3/account/register). If successful you'll get a HTTP Status Code 200 response with a JSON body containing your API key.

    CURL Registering for an API key example

    curl --request POST \ --url https://openapi.data.uwaterloo.ca/v3/account/register \ --header 'content-type: application/x-www-form-urlencoded' \ --data 'email=example@email.com&project=example%20project&uri=https%3A%2F%2Fexample.project.com'

    C# RestClient registering for an API key example

    var client = new RestClient("https://openapi.data.uwaterloo.ca/v3/account/register"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/x-www-form-urlencoded"); request.AddParameter("application/x-www-form-urlencoded", "email=example%40email.com&project=Example%20Project&uri=https%3A%2F%2Fexample.project.com", ParameterType.RequestBody); IRestResponse response = client.Execute(request);

    JavaScript XMLHttpRequest registering for an API key example

    var data = "email=example%40email.com&project=Example%20Project&uri=https%3A%2F%2Fexample.project.com"; var xhr = new XMLHttpRequest(); xhr.withCredentials = true; xhr.addEventListener("readystatechange", function () { if (this.readyState === this.DONE) { console.log(this.responseText); } }); xhr.open("POST", "https://openapi.data.uwaterloo.ca/v3/account/register"); xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded"); xhr.send(data);

  1. Get using!

Querying the API

  1. You'll need to include your API key as an 'X-API-KEY' header for all requests to the API.

  2. As an example of querying the Subjects method.

    CURL Querying Subjects example

    curl --request GET \ --url https://openapi.data.uwaterloo.ca/v3/subjects \ --header 'x-api-key: your_api_key'

    C# RestClient querying Subjects example

    var client = new RestClient("https://openapi.data.uwaterloo.ca/v3/subjects"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", "your_api_key"); IRestResponse response = client.Execute(request);

    JavaScript XMLHttpRequest querying Subjects example

    var data = null; var xhr = new XMLHttpRequest(); xhr.withCredentials = true; xhr.addEventListener("readystatechange", function () { if (this.readyState === this.DONE) { console.log(this.responseText); } }); xhr.open("GET", "https://openapi.data.uwaterloo.ca/v3/subjects"); xhr.setRequestHeader("x-api-key", "your_api_key"); xhr.send(data);

Troubleshooting

Most of the error messages should provide a hint as to what you need to fix. If you are encountering issues you can't work around please report the issue on the GitHub page (https://github.com/uWaterloo/OpenData/issues).