canvas-client
v2.0.2
Published
Typescript library to make accessing the Canvas API more convenient.
Downloads
124
Readme
canvas-client
Typescript library to make accessing the Canvas API more convenient.
Features
Typescript
The canvas client provided by this library has a lot of pre-built methods where we have carefully observed the behavior of the Canvas RESTful API and provided types that accurately reflect what it accepts and returns. The pre-built methods are not complete but they should cover the most common endpoints for server-to-server integrations like course, user, and assignment management.
Rate-limiting and token-splitting
Canvas rate-limits incoming requests to about 20 simultaneous requests per account. This can be rather problematic if you are performing server-to-server operations on behalf of the entire campus via a single service account. This library's solution is two-fold:
- Rate-limit on the client side to ensure canvas never gets overloaded. This way requests to Canvas never fail simply for rate-limiting.
- The default client-side rate limit is a conservative 10 simultaneous requests. It's configurable. If multiple instances of your app share the same token, you may want to reduce this number.
- Support multiple tokens (each MUST come from a separate user account) and load-balance requests across the tokens. This increases your total capacity.
- Note that if you run multiple instances, you STILL want to reduce the max simultaneous requests per token, to avoid getting errors when you have a backlog of requests overwhelming the capacity of your tokens.
GraphQL
We've provided a very simple method for making queries against Canvas' GraphQL API. It only takes care of the fundamentals of GraphQL. We do not provide types for
graphql queries, but the graphql
method does accept a generic so that you can provide the expected return type yourself. GraphQL requests also benefit from token splitting and rate limiting. Tokens and rate limits are shared with RESTful requests.
Testing
Duplicate .env.example
, rename it to .env
and fill in good values for each of the variables. This will allow you to run npm test
successfully.
2.0
The breaking change for 2.0 is node 18+ is required since I got rid of axios in favor of the native fetch api.