Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/instructure/pandarus
A Ruby library for the Canvas API (and code generator for other languages, eventually)
https://github.com/instructure/pandarus
Last synced: 7 days ago
JSON representation
A Ruby library for the Canvas API (and code generator for other languages, eventually)
- Host: GitHub
- URL: https://github.com/instructure/pandarus
- Owner: instructure
- Created: 2014-01-14T21:37:08.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2020-10-15T10:27:47.000Z (about 4 years ago)
- Last Synced: 2024-04-23T06:42:38.337Z (7 months ago)
- Language: Ruby
- Size: 1.85 MB
- Stars: 33
- Watchers: 13
- Forks: 25
- Open Issues: 7
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# What is Pandarus?
Pandarus is a Ruby gem client library for the Canvas LMS API. It is
auto-generated from the Canvas api documentation.
Included in this repo is also the code generator that has the potential to
generate Canvas API support for other programming languages.
Pandarus uses the Swagger 1.2 spec. It depends on the canvas-lms API documentation
to be accurate. If the documentation is accurate, the generated code should
work. However, there are several known cases where the api documentation cannot
conform to the spec, and these cases are broken. We'll try to document known
broken cases below.
## Warning
Please think carefully about whether or not Pandarus makes sense for your use
case. It might make sense to write a smaller wrapper around just the api
endpoints that you need.
**Potential Risks:**
- Pandarus relies on the Canvas API documentation to be accurate. Since there's
nothing directly tying the API documentation to API response generation, it's
possible for these to get out of sync.
- It's also possible for the API documentation to be accurate but malformed
w.r.t the Swagger spec, causing problems with code generation. We've
considered trying to add a validation step to the build, but don't have firm
plans to do so at this time.
- There are cases where the Canvas API returns values (such as arrays of
arrays) that are not possible to represent with the Swagger 1.2 spec.
- Pandarus is built against the master branch at a certain point in time, and
so could contain both APIs that have not yet been deployed to production, or
after some time has passed, could fall behind what is deployed to production.
- Pandarus ignores the "beta" tag on some canvas apis, meaning there is
potential for endpoints in Pandarus to change from version to version.
- Pandarus caches all results in memory by default. For querying large
datasets, this can become a problem. Pass `cache_pages: false` to disable
this.
- We currently don't have a very robust test suite for the generated code.
There are a few tests, and then run on every update and pass, which prevents
the worst kinds of codegen issues from creeping in, but there are probably
still lots of issues with individual endpoints lurking.
**Potential Benefits:**
- Pandarus is "complete", in that it should contain all documented API
endpoints.
- It's pretty easy to get started and play around with the API.
Pandarus was created internally as an experiment, and is only used sporadically
internally. As such, it's only updated sporadically as well. It's provided as
a way to experiment with the Canvas API, but **please understand the risks
before using it in a production application**.
## Installation
```
gem install pandarus
```
## Example Usage
```ruby
require 'pandarus'
client = Pandarus::Client.new(
prefix: "https://pandamonium.instructure.com/api",
token: "[YOUR API TOKEN HERE]")
client.get_single_course_courses(1)
# => 1 ...>
```
## Documentation
See the Canvas API documentation that Pandarus is built from:
http://api.instructure.com/
Pandarus method names are very similar to the descriptions in the
documentation. If you follow three rules, you will be able to access the full
API:
1. All descriptions get lower-cased and spaces become underscores
2. If there is an 'a', 'an' or 'the' in the description, ignore it
3. If there are two ways to access an API call (such as via `/courses` and
`/sections`) then add a `_courses` or `_sections` suffix
**Examples:**
- The API documentation describes a "Get a single account" API. This becomes
`get_single_account`
- "Reserve a time slot" becomes `reserve_time_slot`
- "Get a single course" becomes EITHER `get_single_course_courses` OR
`get_single_course_accounts` because there are two ways to access the API.
## Code Generation
To generate the Ruby gem from Canvas's api-docs.json file:
1. Install Java 1.8 SDK
2. Install maven (e.g. `brew install maven`)
3. Set the environment variable `CANVAS_DIR` if your canvas checkout is not
located at the relative path `../canvas-lms`.
4. Run `./build-all`
## Directory Structure
- [`api/`](api/) - This is a copy of the api swagger docs generated by canvas. It is
autogenerated and should not be modified by hand.
- [`clients/`](clients/) - This is where the Ruby gem lives.
- `clients/ruby/lib/pandarus/{models/*,api_base.rb,models.rb}` are all
auto-generated.
- [`api_base.rb`](clients/ruby/lib/pandarus/api_base.rb) is where all the
individual api calls live.
- [`codegen/`](codegen/) - This is the scala code that uses Swagger to run the
code gen.
## Known Issues
- Group Categories "Assign unassigned members" returns two different object
types (`GroupMembership` or `Progress`) depending on the input params, which
Swagger does not handle.
- The SisImport object has two fields `processing_warnings` and
`processing_errors` which are arrays of arrays. This datatype can't be
expressed in Swagger.
## TODO
- Look into validation of the swagger json files with
https://github.com/apigee-127/swagger-tools