npm i @kth/canvas-api
Node.JS HTTP client (for both TypeScript and JavaScript) based on got for the Canvas LMS API
First, generate a token by going to «YOUR CANVAS INSTANCE»/profile/settings
. For example https://canvas.kth.se/profile/settings. Then you can do something like:
const canvasApiUrl = process.env.CANVAS_API_URL;
const canvasApiToken = process.env.CANVAS_API_TOKEN;
const Canvas = require("@kth/canvas-api").default;
async function start() {
console.log("Making a GET request to /accounts/1");
const canvas = new Canvas(canvasApiUrl, canvasApiToken);
const { body } = await canvas.get("accounts/1");
console.log(body);
}
start();
In TypeScript, use import
:
import Canvas from "@kth/canvas-api";
console.log("Making a GET request to /accounts/1");
const canvas = new Canvas(canvasApiUrl, canvasApiToken);
const { body } = await canvas.get("accounts/1");
console.log(body);
This package implements one function to perform SIS Imports (i.e. call the POST sis_imports endpoint).
Note: this is the only function that calls a specific endpoint. For other endpoints you should use
canvas.get
,canvas.requestUrl
,canvas.listItems
andcanvas.listPages
This package does have pagination support which is offered in two methods: listItems
and listPages
. Let's see an example by using the [GET /accounts/1/courses]
endpoint.
If you want to get all pages you can use listPages
:
const canvas = new Canvas(canvasApiUrl, canvasApiToken);
const pages = canvas.listPages("accounts/1/courses");
// Now `pages` is an iterator that goes through every page
for await (const coursesResponse of pages) {
// `courses` is the Response object that contains a list of courses
const courses = coursesResponse.body;
for (const course of courses) {
console.log(course.id, course.name);
}
}
To avoid writing two for
loops like above, you can call listItems
, that iterates elements instead of pages. The following code does exactly the same as before. Note that in this case, you will not have the Response
object:
const canvas = new Canvas(canvasApiUrl, canvasApiToken);
const courses = canvas.listItems("accounts/1/courses");
// Now `courses` is an iterator that goes through every course
for await (const course of courses) {
console.log(course.id, course.name);
}
This package does not contain type definitions to the objects returned by Canvas. If you want such types, you must define them yourself and pass it as type parameter to the methods in this library.
For example, to get typed "account" objects:
// First you define the "Account" type (or interface)
// following the Canvas API docs: https://canvas.instructure.com/doc/api/accounts.html
interface CanvasAccount {
id: number;
name: string;
workflow_state: string;
}
// Then, you can call our methods by passing your custom type as type parameter
const { body } = await canvas.get<CanvasAccount>("accounts/1");
console.log(body);
By default, this library throws CanvasApiError
exceptions when it gets a non-200 HTTP response from the Canvas API. You can catch those exceptions with any of the methods:
const canvas = new Canvas(canvasApiUrl, "-------");
const pages = canvas.listPages("accounts/1/courses");
try {
for await (const coursesResponse of pages) {
const courses = coursesResponse.body;
for (const course of courses) {
console.log(course.id, course.name);
}
}
} catch (err) {
if (err instanceof CanvasApiError) {
console.log(err.options.url);
console.log(err.response.statusCode);
console.log(err.message);
}
}
By default, CanvasApiError
thrown by this library contains a property response
with a very big object. If you would like to have a smaller response
in the error object, you can modify the errorHandler
property:
import CanvasApi, { minimalErrorHandler } from "@kth/canvas-api";
const canvas = new CanvasApi("...");
canvas.errorHandler = minimalErrorHandler;
You can also pass a custom function in the .errorHandler
property: that function will be called with whatever is thrown by got
. Read more about errors in Got here
Notes:
- Argument
err
in the custom handler will be the error thrown bygot
, so it will never beCanvasApiError
- Make sure the function you pass never returns something.
You can use this function to create your own error objects:
import CanvasApi from "@kth/canvas-api";
const canvas = new CanvasApi("...");
canvas.errorHandler = function customHandler(err: unknown): never {
if (err instanceof HTTPError) {
throw new CustomError(`Oh! An error! ${err.message}`);
}
throw err;
};
-
Do not implement every endpoint. This package does not implement every endpoint in Canvas API This package also does not implement type definitions for objects returned by any endpoint nor definition for parameters. That would make it unmaintainable.
-
Offer "lower-level" API instead of trying to implement every possible feature, expose the "internals" to make it easy to extend.
Example: you can use
.client
to get theGot
instance that is used internally. With such object, you have access to all options given by the library got