For all of you who, like me, are intrigued by Instructure Canvas’s open API but just haven’t had a big block of time to play with it, well, just get yourself a browser plug-in that operates as a REST client and you can be up and running in no time. You’ll be surprised at what doors this might open.
1. Install a REST client extension.
Chrome has several great extensions to this end, but so far I like Advanced Rest Client. It lets you save requests and view your history.
For Firefox the most popular REST client is intuitively named RESTClient. Same basic functionality, but with nice tabs to view the output in different ways.
2. Create a Canvas Access Token in your account profile.
The access token will provide a secure key, if you will, to Canvas with all your own unique permissions and enrollments. Most modern web services help you create these to securely talk with other systems.
Login to Canvas, click on your name, and scroll down to Approved Integrations. If you don’t already have a token, click New Access Token.
Give your token a label (purpose) and expiration date (if you want).
Copy that really long string that Canvas generates and paste it into a text document for later reference–you’ll need it to talk to Canvas via your REST client.
3. Pick an API resource or action from the Canvas documentation
Start by going to the Canvas API documentation. Browse through the Authentication page as well as the Resources, which contain all the currently possible the API actions and outputs.
I don’t have a lot of time to get into API calls and REST, but you can think of it as simply a message sent to a server with an authorization method that tells the server how to respond based on the target and the access token. In this case we’re using the GET method. The API calls will simply be HTTPS URLs with the access token appended as a variable. The URL will change based on what data in Canvas you want to access.
For example, if I want to see all of my page view data, I start with the base Canvas HTTPS URL:
https://canvas.instructure.com
I then append the location of the API resource or action:
/api/v1/users/:user_id/page_views
Be sure to replace :user_id with the numeric value of the user id (or course or account id) you want to access. In this case I want my own. It’s easy to grab this from the end of the URL of my profile page (which happens to be https://canvas.instructure.com/users/123456, so my user id = 123456)
Finally, you’ll need to append your access token as the value of a variable:
?access_token=somereallylongsecurestringhere
So it looks something like this:
https://canvas.instructure.com/api/v1/users/123456/page_views?access_token=somereallylongsecurestringhere
This URL is what we’ll feed our REST client in the next step.
4. Run the API through the browser REST client
Open your REST client add-on/extension and paste in the URL customized for the API action you want to perform plus the course/account/user id plus your access token.
Be sure you’re using the right method (typically GET) before clicking send.
You’ll end up with output below. I recommend looking at the JSON formatted response. This data is organized in name/value pairs, but can also contain objects, so a whole lot of data in a very simple format is possible here.
This gives you a glimpse of the possible data exchanges that Canvas makes available via its open API. Your ability to get data will depend upon your role and permissions within Canvas. Obviously student and teacher users will have far less access than admins at any sub-account level.
In real-world practice, you’ll need to know a bit more than this. But the essence is that you’d use any number of scripting languages to request the data from the Canvas API, parse it in JSON format, then do wonderful, magical things–like calculate an individual user’s course progress in order to dynamically generate a badge. Or not.
