Home Getting Started

While we work through visibility issues on the Confluence platform where the majority of the documentation is, this is a carbon copy of the getting started documentation for v3 of the Open Data API.

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/).

Getting an API key

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).

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 your email in the body.

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 protected]&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);

An email will arrive shortly to the email address you provided with your API key, and a Confirmation code.

POST to the Confirm method (v1/Account/Confirm) your email and Confirmation code to activate your API key.

CURL Confirmation of account example

curl --request POST \
  --url https://openapi.data.uwaterloo.ca/v3/account/confirm \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'email=example%40email.com&code=your_confirmation_code_from_email'

C# RestClient Confirmation of account example

var client = new RestClient("https://openapi.data.uwaterloo.ca/v3/account/confirm");
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&code=%7Byour-confirmation-key%7D", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
JavaScript XMLHttpRequest Confirmation of account example  Collapse source
var data = "email=example%40email.com&code=%7Byour-confirmation-key%7D";
 
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/confirm");
xhr.setRequestHeader("content-type", "application/x-www-form-urlencoded");
 
xhr.send(data);

On success you'll get back a HTTP status code 200 response, or a 400 Bad Request in case of any failures. On success your account API key is confirmed and activated

Get using!

Querying the API

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

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).