API - Getting Started for the Absolute Beginner

[lmurray2]

Canvas Developers, 

I am an absolute beginner in the Canvas development world and would like to look at any resources that would introduce me to the Canvas API. Any suggestions out there? 

Logan

[wurzel]

Hi  Logan,

The main page for API documentation is here.  I suggest skimming through the "Basics" and "Oauth 2" sections. Then head on over to the Live API page and play with some of the available fields to see what the data looks like. You'll spend a lot of time in the /courses, /enrollments, and /users sections, so I'd look there first.  If you are brand new to RESTful apis, O'Reilly book on the topic is a good crash course.

[ColinMurtaugh]

I'll add a recommendation for the Postman app as a great tool to use when experimenting with RESTful APIs:

Postman | Supercharge your API workflow 

...and  @garth ‌ has a great post on how to use Postman with the Canvas API: API Testing: Postman 

--Colin

[ddieckmeyer]

Hi Logan,

As a new API user myself, I found this site to be useful for converting the curl examples to Python. 

http://curl.trillworks.com 

You are able to choose between python, PHP and Node.js 

In Canvas API docs, under 'Courses - Recently logged in students' you'll find this curl example listed. 

curl -H 'Authorization: Bearer <token>' \      https://<canvas>/api/v1/courses/<course_id>/recent_users

Pasting into the page above converts to this:

import requests

headers = {
'Authorization': 'Bearer <token>',
}

requests.get('https:///%3Ccanvas%3E/api/v1/courses/%3Ccourse_id%3E/recent_users', headers=headers)

Hope this helps!

~ Dave

[maguire]

I have a number of examples of using the API via python programs at GitHub - gqmaguirejr/Canvas-tools: Some tools for use with the Canvas LMS. Additionally, there are examples of using the API via an external LTI tool (written in Ruby) at GitHub - gqmaguirejr/E-learning: E-learning project for using Canvas .  There are series of examples at Course Modules: Chip sandbox  . 

[phanley]

Just as an addition, if you prefer a classic terminal experience the combination of curl and jq is pretty sweet, especially for GET (but not too bad for the others) 

for GETs it's as easy as setting up an alias: 

alias canvapi="curl -H \"Authorization: Bearer {secretlongtokenstring}\""‍

and then adding the api url and a quick pipe to jq, like this

canvapi https://uni.instructure.com/api/v1/courses/:course_id | jq ‍

which gets you e.g.

{

  "id": 20512,

  "name": "   Dank Memes and Dark Dreams",

  "account_id": 5,

  "etc": "etc.",

... 

}

all nice in your terminal.  

I have postman and some other similar apps, but I end up just using bash terminal & curl/jq most of the time (at least until something needs to be automated and turned into a tool for users)

jq has rich set of abilities beyond just pretty printing -- you can transform the data you get from the api and bend it to your needs. For example, if you just needed the id and name in the command above (try playing around with this, it's fun):

canvapi https://uni.instructure.com/api/v1/courses/:course_id \
| jq ‍{id: .id, name: .name}‍‍‍

Of course all normal shell rules apply, so you can do some really tedious things quickly by combining the jq processing powers with shell scripting.

Here's an example I had lying around that can restore groups nn a production course from a beta course (assuming the instructor catches that they somehow broke their course groups before beta re-syncs (also, this specific issue hasn't come up for over a year, but I just tested it and it seems like it still works, so I guess that's good?

#!/bin/bash
####  invoke with script name and canvas course id of course that need to be fixed
####  ./fixGroupOops.sh 20512
#### this will make all :course_id groups on production mirror beta 
#### so be sure that is what you want

## set variables (edit these as necessary)
if [ $1 ]; then
 crs_id=$1
 token={secretlongtokenstring}
 beta_can=uni.beta.instructure.com
 can=uni.instructure.com
 canvapi="curl -sS -H \"Authorization: Bearer $token\""
 alias canvapi="curl -sS -H \"Authorization: Bearer $token\""
 curl_b_group_ids="$canvapi -X GET \"https://$beta_can/api/v1/courses/$crs_id/groups\""
 
 echo "restoring groups from $beta_can/courses/$crs_id to $can/courses/$crs_id"
 
 #mk a dir for the crs_id 
 mkdir $crs_id
 
 ## get groups for course
 eval $curl_b_group_ids | jq '.[] | .id' | while read group_id; do \
 echo "getting group $group_id from $beta_can"; \
 curl_group_id="$canvapi -X GET \"https://$beta_can/api/v1/groups/$group_id/users\" -F \"per_page=1000\""; \
 eval $curl_group_id | jq '.' > $crs_id/$group_id; done
ls $crs_id | while read group_id; do cat $crs_id/$group_id | jq -r -c '.[] | .sis_user_id'| \
 while read -r user_name; do \
 fix_oops="$canvapi -X POST \"https://$can/api/v1/groups/$group_id/memberships\" -F \"user_id=sis_user_id:$user_name\"";\
 echo "restoring $user_name to $can/courses/$crs_id/groups/$group_id"
 eval $fix_oops| jq '.' >> $crs_id/fix_log.txt; done;done
 exit 0
fi‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

It saves everything in a sub folder so you can look over it and make sure (after the fact) that it worked. Not really sure how often this specific one comes up (I think we only ever had to do it for one or two faculty members, and they eventually figured out how to not have this problem), but it's a good example of 22 lines of code saving hours of tedium (the course that caused this to be written had many groups involving hundreds of students - a nightmare to check in the groups ui) -- note the -F \"per_page=1000\" might no longer work in which case moving to an api tool might be prudent...

[adamwarecx · Accepted solution]

A great place to start your API journey is here: https://community.canvaslms.com/t5/Canvas-Developers-Group/Canvas-APIs-Getting-started-the-practical...