Super simple to use
This module wraps the Canvas Api handling pagination and throttling. Giving easy access to the main CRUD operations, and making the other more specific calls easier as well.
// Example: Publish all Modulesconst canvas =canvassubdomain = 'example' // default:byui// Gets the course shell (doesn't send any requests)const course = canvas// Gets the data for all modules for this courseawait coursemodules// modules inherits from Array, so Array methods workcoursemodules// Updates everything in the course that has been changedawait course
Table of contents
Get Started
Install
npm i --save canvas-api-wrapper
Setup
var canvas =// https://<subdomain>.instructure.com (default: byui)canvassubdomain = '<subdomain>'
Authorization:
canvasapiToken = "<TOKEN>"
# Powershell$env:CANVAS_API_TOKEN="<TOKEN>"# CMDset CANVAS_API_TOKEN=<TOKEN># Linux & Macexport CANVAS_API_TOKEN="<TOKEN>"
Settings
This library handles all of the throttling, so that you won't go over your rate limit. But you may want to tweek the settings to speed it up or slow it down
// the subdomain to be used in the default baseUrl// https://<subdomain>.instructure.comcanvassubdomain = 'byui'; // The baseUrl to be used. Useful to overwrite when running// a dev/local version of the canvas-lms. // // canvas.baseUrl = https://localhost:8080//// The default will use the // subdomain setting as the subdomain, this functionality// is not avaliable if over writtencanvasbaseUrl = 'https://<subdomain>.instructure.com' // Canvas uses a rate-limit point system to handle spamming. Canvas// currently fills your account to 700 'points' though subject to change// then subtracts from your 'points' every time you make a call. If // you go below 0 then canvas will start sending you 403 (unauthorized) // statuses. So when your account goes under the 'rateLimitBuffer'// this module will halt the requests until it gets filled back to // the 'rateLimitBuffer'. Give it a pretty large buffer, it tends to // go quite a ways past the buffer before this module catches it.canvasrateLimitBuffer = 300; // How many to send synchronously at the same time, the higher this// number, the more it will go over your rateLimitBuffercanvascallLimit = 30; // How much the calls are staggered (milliseconds) especially at the// beginning so that it doesn't send the callLimit all at the same timecanvasminSendInterval = 10; // After it goes under the rateLimitBuffer, how often (in milliseconds) // to check what the buffer is at now, this should be pretty high because// there will be a lot of threads checking at the same time.canvascheckStatusInterval = 2000;
Debugging
This library ambiguates which calls it's making quite a bit, especially with the wrapped calls. So to make sure it's not making excess calls. Or to just making sure it's doing what it should be you can assign canvas.oncall
a function as an event handler.
canvas{console}await canvaspages/*{ method: 'POST',url: 'https://byui.instructure.com/api/v1/courses/11310/pages/',body:{ wiki_page:{ title: 'Hello World',body: '<h1>Hello World</h1>',published: true } } }*/
Standard Calls
Use awaits or the optional callback
var modules = await /* ----------- OR -------------- */
If a post, put, or delete request the second argument is the request body
await canvas
If a get request, the second argument is the query object
var queriedModules = await
Signatures
// uses a GET requestcanvascanvascanvascanvascanvas
Wrapped Calls
The CRUD operations for files, folders, assignments, discussions, modules, pages, and quizzes are wrapped for convenience. The can be accessed through the Course Class which is created through canvas.getCourse(id)
Item
Course extendsfiles
<Files>folders
<Folders>assignments
<Assignments>discussions
<Discussions>modules
<Modules>pages
<Pages>quizzes
<Quizzes>
var course = canvas// this will get the course object and attach the properties to the courseawait course// allowing you to docoursecourseis_public = trueawait course// using getComplete, will retrieve every single item and// their sub items in the course. This is not recommended (of course) but// can be helpful in certain situations where you need every itemawait coursecoursequizzes0questions0coursemodules0moduleItems0courseassignments0// Update searches through all of the children for changes, and updates// only those with changes. So just doing course.update() will push all// changes made anywhere in the course.await course
Items extends Array
The abstract class which all of the lists of items inherit from
- async
update( [callback] )
- Updates all of the items that have had changes made to them or their children
const course = canvasawait courseassignmentscourseassignments// Only updates items named potato, because those were the only ones changedawait courseassignments
- async
create( data, [callback] )
<Item>- Creates the item in canvas, with the given data. And adds it to the items property
data
<Object> the properties to add to the created item
const course = canvasconst page = await coursepagesconsole
- async
get( [callback] )
<[Item]>- Retrieves all of the children items from canvas
const course = canvas// you don't have to save it to a variable,// you can also just access the array through `course.modules`// this just saves you from writing `course` everywhereconst modules = await coursemodulesconsole
- async
getComplete( [callback] )
<[Item]>- Retrieves all of the children items from canvas and all of their sub items such as the
questions
in aquiz
or thebody
in apage
- Retrieves all of the children items from canvas and all of their sub items such as the
const course = canvasconst modules = await coursemodules// normally you would have to call `get()` on each of the// modules ( modules[0].get() ) in order to get the moduleItemsconsole
- async
getOne( id, [callback] )
<Item>- Retrieves a single item from canvas by id
id
<number> the id of the item to grab
const course = canvasconst folder = coursefoldersconsole
- async
getOneComplete( id, [callback] )
<Item>- Retrieves a single item from canvas by id including all of it's sub items such as the
questions
in aquiz
( thebody
inpage
is already included because your only getting a single item ) id
<number> the id of the item to grab
- Retrieves a single item from canvas by id including all of it's sub items such as the
const course = canvasconst quiz = coursequizzesconsole
- async
delete( id , [callback] )
- Removes an item from canvas, and from the local list
id
<number> the id of the item to delete
const course = canvasawait coursequizzesconst questions = await coursequizzes0questionsawait questions
Item
The abstract class for the items to inherit from
getId()
<number>getTitle()
<string>setTitle( title )
getHtml()
<string>setHtml( html )
getUrl()
<string>getSubs()
<[Items]> - Array of children Items- async
get( [callback] )
<Item>- Retrieves the item from canvas
- async
getComplete( [callback] )
<Item>- Retrieves the item from canvas including the sub items such as the
questions
in aquiz
( thebody
inpage
is already included because your only getting a single item )
- Retrieves the item from canvas including the sub items such as the
- async
update( [callback] )
- Only updates if properties have been changed on the Item since it was last gotten, also updates all of it's sub children who have been changed
- async
delete( [callback] )
- Will delete item, and remove it from it's parent list
Items
Assignments extendsItem
Assignment extendsItems
Discussions extendsItem
Discussion extendsItems
Files extends- Doesn't have a create method
Item
File extendsItems
Folders extendsItem
Folders extendsItems
Modules extendsItem
Module extendsmoduleItems
<ModuleItems>
Items
ModuleItems extendsItem
ModuleItem extendsItems
Pages extendsItem
Page extendsItems
Quizzes extendsItem
Quiz extendsquestions
<QuizQuestions>
Items
QuizQuestions extendsItem
QuizQuestion extendsItem Gets and Sets
Type | getId | getTitle/setTitle | getHtml/setHtml | getUrl | getSubs |
---|---|---|---|---|---|
Course | id | name | /courses/<course> | [ files<Files>, folders<Folders>, assignments<Assignments>, discussions<Discussions>, modules<Modules>, pages<Pages>, quizzes<Quizzes> ] | |
Assignment | id | name | description | html_url | |
Discussion | id | title | message | html_url | |
File | id | display_name | /files/?preview=<id> | ||
Folder | id | name | folders_url | ||
Module | id | name | /modules#context_module_<id> | [ moduleItems<ModuleItems> ] | |
ModuleItem | id | title | html_url | ||
Page | page_id | title | body | html_url | |
Quizzes | id | title | description | html_url | [ questions<QuizQuestions> ] |
QuizQuestion | id | question_name | question_text | /quizzes/<quiz>/edit#question_<id> |