Project

lms-api

0.01
The project is in a healthy, maintained state
Wrapper for the Instructure Canvas API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Project Readme

LMS API

This project provides a wrapper around the Instructure Canvas API.

Installation

To install, add lms-api to your Gemfile:

    gem "lms-api"

Configuration

Your app must tell the gem which model is used to represent the authentication state. For instance, if you're using ActiveRecord, you might have an Authentication model, which encapsulates a temporary API token.

class Authentication < ActiveRecord::Base
  # token: string
end

Then, you tell the gem about this model:

LMS::Canvas.auth_state_model = Authentication

This allows the gem to transparently refresh the token when the token expires, and do so in a way that respects multiple processes all trying to do so in parallel.

Usage

To use the API wrapper, instantiate a LMS::Canvas instance with the url of the LMS instance you want to communicate with, as well as the current authentication object, and (optionally) a hash of options to use when refreshing the API token.

Require the gem: require "lms_api"

auth = Authentication.first # or however you are storing global auth state
api = LMS::Canvas.new("http://your.canvas.instance", auth,
        client_id: "...",
        client_secret: "..."
        redirect_uri: "..."
        refresh_token: "...")

You can get the URL for a given LMS interface via the ::lms_url class method:

params = {
  id: id,
  course_id: course_id,
  controller: "foo",
  account_id: 1,
  all_dates: true,
  other_param: "foobar"}

url = LMS::Canvas.lms_url("GET_SINGLE_ASSIGNMENT", params)

Once you have the URL, you can send the request by using api_*_request methods:

  • api_get_request(url, headers={})
  • api_post_request(url, payload, headers={})
  • api_delete_request(url, headers={})
  • api_get_all_request(url, headers={})
  • api_get_blocks_request(url, headers={}, &block)

The last two are convenience methods for fetching multiple pages of data. The api_get_all_request method returns all rows in a single array. The api_get_blocks_request method yields each "chunk" of data to the block.