cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 
lmurray2
Community Participant

API - Getting Started for the Absolute Beginner

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

Labels (1)
5 Replies
wurzel
Community Participant

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
Community Champion

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
Community Participant

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
Community Champion

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
Community Contributor

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