Nuanced Pterodactyl Monk

    @kth/canvas-api
    TypeScript icon, indicating that this package has built-in type declarations

    4.2.2 • Public • Published

    Canvas API (for TypeScript and JavaScript)

    npm i @kth/canvas-api

    Node.JS HTTP client (for both TypeScript and JavaScript) based on got for the Canvas LMS API

    Getting Started

    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);

    Concepts

    🆕 New from v4. SIS Imports

    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 and canvas.listPages

    listItems and 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);
    }

    Typescript support

    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);

    Error handling

    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);
      }
    }

    Shorter error objects

    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;

    Custom error objects

    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 by got, so it will never be CanvasApiError
    • 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;
    };

    Design philosophy

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

    2. 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 the Got instance that is used internally. With such object, you have access to all options given by the library got

    Keywords

    none

    Install

    npm i @kth/canvas-api

    DownloadsWeekly Downloads

    127

    Version

    4.2.2

    License

    MIT

    Unpacked Size

    23.6 kB

    Total Files

    9

    Last publish

    Collaborators

    • kthwebmaster
    • wkchung
    • exacs
    • ssundkvist
    • kth-ci
    • emilstenberg