ubc / node-canvas-api Goto Github PK

View Code? Open in Web Editor NEW

67.0 6.0 22.0 1.36 MB

Access the Canvas API using Node.js. 54 functions (and counting)! Pull requests are welcome and appreciated.

License: MIT License

JavaScript 100.00%

node canvas lms api instructure

node-canvas-api's Introduction

Canvas LMS API for Node.js

Canvas API functions bundled as a NPM package for Node.js.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for use with your own API tokens and Canvas domains.

Prerequisites

Install Node 8.0.0 or greater.

Installation

To use with node:

$ npm install node-canvas-api

Then, in wherever you want to use this package:

const canvasAPI = require('node-canvas-api')

Rename the sample.env file to .env and add your institution's domain and API access token.

Attached to the canvasAPI are a bunch of functions. Run the attached functions!

Example Usage

Get information about self:

const canvasAPI = require('node-canvas-api')

canvasAPI.getSelf()
  .then(self => console.log(self))

Get students in a course:

const { getUsersInCourse, getOptions } = require('node-canvas-api')

getUsersInCourse(12345, getOptions.users.enrollmentType.student) // first argument is Canvas course ID
  .then(students => console.log(students))

Contribute

Contributions are welcome and greatly appreciated!

How to contribute

Create an issue describing what contribution you are planning to make.
Fork the repo.
Add your contributions to the source directory (and not the src directory. This directory is generated by Rollup during the build phase, and is what gets published to npm.)
If you add a file to source, please add the file to the existing index.js inside source, so that during the build your contribution will be included in src.
Test your code by creating a file in the root of the project directory, importing your code addition from src, and running it.
Once you're happy with your contribution, open an pull request and I'll take a look.

Hypothetical scenario for adding new feature

Add new file to source folder (say that the new file you want to add is getUsersWithGradeThreshold.js)
In the source folder, there’s an index.js file that lists all of the files you want exported to src. There you will add: export { default as getUsersWithGradeThreshold } from './getUsersWithGradeThreshold'
Run npm run build, which will build the project and output your new function into src.
In the index.js at the root of the project that you create (this is not the index.js that’s in the source folder), import your new file from src like this: const getUsersWithGradeThreshold = require('.src/getUsersWithGradeThreshold') and test by running the code: node index.js.
Once you’re happy that it works, create a PR.

Usage

License

This project is licensed under the MIT License.

node-canvas-api's People

Contributors

Stargazers

Watchers

node-canvas-api's Issues

Better rate-limiting implementation

Current rate-limiting is static, relying on https://www.npmjs.com/package/bottleneck, instead of dynamically throttling depending on the X-Rate-Limit-Remaining header on the response.

Implementing proper rate-limiting will:

Improve performance, potentially dramatically.
Reduce chance of accidentally hitting the rate limit when making batch changes and causing an absolute headache because it becomes difficult to determine which requests succeeded and which requests failed (as happened recently to me when running https://github.com/ubccapico/restore-speedgrader-comments.

Error handling example?

Do you have any examples of catching an error and not displaying the FULL error details?
For example, if I call getUsersInCourse() and pass in an invalid course_id (coming in from a CSV), I get ALL the response details - pages of them. I'll like to be able to catch the error, display a one-line error message and move on to the next action (or exit). In my specific use case, I'm looping through courses pulling the users and in the case of an invalid course, I'd like to just skip it and move on to the next one.

Add modules getOptions

Add the following options

      items: 'include[]=items',
      content_details: 'include[]=content_details'

Add Discussion getOptions, allow passing options to getDiscussionTopics

Add the following options:

      all_dates: 'include[]=all_dates',
      sections: 'include[]=sections',
      sections_user_count: 'include[]=sections_user_count',
      overrides: 'include[]=overrides'
      position: 'orderby=position',
      recent_activity: 'orderby=recent_activity',
      title: 'orderby=title'
      locked: 'scope=locked',
      unlocked: 'scope=unlocked',
      pinned: 'scope=pinned',
      unpinned: 'scope=unpinned'
    only_announcements: 'only_announcements=true',
      all: 'filter_by=all',
      unread: 'filter_by=unread'

No license

Could you please add a license to this repo?

Feature: Add Module Support

https://canvas.instructure.com/doc/api/modules.html

List module items as getModules
Show module item as getModuleItem

Scope:

Just the two additional function files, no breaking changes.

Adding search option to getUsersInAccount

I'm working on a proof of concept user lookup tool and need to add the ability to get a search result of all users in an account instead of all of them. I have that working and will create a pull request.

Feature Request: Add User Creation

I've added a new function called createUser() for creating users in Canvas LMS.
The function takes 2 params:

accountId: the account to associate this user with.
body: the object of the user to be created.

Adding onto the README

Hi Justin!

I had a look at your canvas API for node and tried playing around with it. It's amazing! I wanted to create extensions to this, but am not entirely sure what to do for a few things. Would you perhaps have the answer to these questions?

Is ' npm run build:cjs ' the command to build the files? (I want to run some of the example methods you created in the src/source files, but am not able to).
In the README, it is asked to create my contributions in the source directory. I'm trying to run the example usage you have provided in the README in the src folder (with the command 'node index.js' on the terminal) and it is telling me that getSelf() is not defined, yet I believe it is being imported within the same folder. Could you perhaps walk me along the steps to build and test this application so I can add onto the documentation you have in the README?