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

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

   CURL Registering for an API key example Expand source

   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 Expand source

   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 Expand source

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

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

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

   CURL Confirmation of account example Expand source

   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 Expand source

   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 Expand 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);

5. 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
6. 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 Expand source

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

   C# RestClient querying Subjects example Expand source

   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 Expand source

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