API Setup and Documentation

The Wisr API allows programmatic access to data stored on the Wisr Platform. It is built on REST principles and has resource-oriented URLs that use appropriate HTTP methods and response codes. Using an authentication bearer token, a member is able to easily send HTTP requests to retrieve data and in some cases modify data.

API Reference

The Wisr API Reference is a complete list of all Wisr API endpoints available. You can access it by going to https://subdomain.wisr.io/docs (replace subdomain with your school's Wisr specific subdomain). Once you have access to the API, the URLs in this reference will be used to retrieve specific data resources and explore the API.

Authentication

Authentication is performed via HTTP Basic Auth. Each API request needs to include your API Token in order to authenticate and authorize access to your data. This token can be retrieved by taking the following steps:
  1. Request API access from the Wisr Team by clicking the contact button on this page and submitting a request (we will create an admin account in the API Testing environment).
  2. Log in to your admin account at https://api-sandbox.wisr-staging.com with your username and password.
  3. Retrieve your API Token by going to the following URL and observing the key field: https://api-sandbox.wisr-staging.com/api/v1/me/authtoken
  4. Optional: Save your token in a secure way (we recommend using a password vault application like 1Password).
  5. Include your token in an Authentication header on each request to the API. No username or password is needed. Example -- Authorization: Bearer d33bc008cadefdfe15f514fe3df55bf0c82f039f

Regenerating Your Token

You can regenerate and replace your token by submitting the following request:
POST https://wisr.wisr-staging.com/api/v1/authtokens/{token}/regenerate
This can be used if your token has been compromised or exposed. The endpoint will return a new token and consequently make the old token obsolete. WARNING: your old token will no longer be authorized for requests and any place it is being used needs to be updated with the new token.

Testing

In this guide and other API documentation, all of the URLs reference the API testing domain ( https://api-sandbox.wisr-staging.com). This is where all development and testing should be done. After your application has been fully tested, a production token can be generated for you and and the application can be used against your Wisr Production environment (i.e. https://yoursubdomain.wisr.io).

We recommend using a HTTP client tool like Postman to test with. Postman is free and has built in tools to quickly and easily explore an API. A preview of testing the Wisr API with Postman is as follows: 

Pagination

Top-level resources use pagination when listing multiple objects. The pagination has a default of 25 objects per page. This can be overridden by including the page_size query parameter with a request. For example if you want limit the number of profiles per page to 10 you can send the request: 
GET https://wisr.wisr-staging.com/api/v1/profiles?page_size=10

Headers

When a paginated request is made (i.e., there are more records available than how many were returned in the request), the Wisr API will automatically include a couple headers for your convenience.

X-Total-Count

The X-Total-Count header provides the total number of records in the result set. 

Link
The Link header provides api links to the  first, next, and last pages of the paginated result set. You can use these to iterate through the api or skip to the beginning/end.
Link <https://api-sandbox.wisr-staging.com/api/v1/profiles?page=1>; rel="first", <https://api-sandbox.wisr-staging.com/api/v1/profiles?page=2>; rel="next", <https://api-sandbox.wisr-staging.com/api/v1/profiles?page=2>; rel="last"<br>

Rate Limiting

The Wisr API throttles API requests from your token at the following maximum request rates:

Requests per minute: 30
Requests per day: 2,000
Based on these limits, you can query the API up to 2,000 times in a given day, and the API will allow you to burst up to 30 requests a minute. If you're executing requests in a loop, such as reading all profile records, there are some techniques you may use to stay within these burst limits. You can:
  • Increase the page_size to 100 to reduce the overall number of requests
  • Add a sleep of 2 seconds in your loop so that your script is executing a request every 2 seconds, which would stay under the 30/min burst limit
If you need these limits to be increased, please reach out to your Wisr Customer Success Manager.

Next Steps

Please contact us to get started with setting up your API access. If you already have access but need assistance concerning the Wisr API, please don't hesitate to reach out your Wisr Customer Success Manager clicking the contact button on this page.

Still need help? Contact Us Contact Us