All things API

[scottdennis]

Have a question about the Canvas APIs? Have a cool API integration you'd be willing to share? If so, please post here.

[katerina_newton]

Hi, I am completely new to this. I am actually an Admin for our institution and not a developer but I would like to learn some basics about APIs. Could you recommend some introductory material I can review to understand them better? Thank you in advance!

[jblumberg]

Katerina.... 

I think the most intuitive thing is to play with URLs right in the browser, for instance, try going to the URL:

https://yourinstance.instructure.com/api/v1/courses

(Make sure you are logged into Canvas in another browser tab first)

You will get a list of courses you are enrolled in.  It will look a bit cryptic, the encoding is called JSON, but it is still very human readable.

You can see how to build these URL requests by looking at Canvas's API reference:

Canvas LMS REST API Documentation​

Pick a programming language you like, and most of them have an easy way of reading JSON. 

Easiest way to get started is to think about writing custom reports.  A simple command line report that creates a .csv file is not many lines of code.  I recommend sticking to "GET" requests (read-only)  till you get comfortable.  If you make requests other than "GET" requests make sure you test on the beta or test sites first.

Best to pick a programming language first (many non-programmers like powershell).  If someone at your institution writes code, talk to them and consider using whatever they use.  Then read up on how to make REST API calls and handle JSON in that language....  most likely you can find some code you can modify.

Josh

[katerina_newton]

Josh, thank you so much for taking the time to write your reply. I will definitely look into it! Picking a programming language was one of my questions. Yes, we do have code-writers but they provide support to 21 campuses in our organization and I only represent one campus (which also happens to be the biggest one) so we are looking at writing some custom APIs for our campus. Thank you again and have a great day!

[jblumberg]

A scripting style language is simplest...  PowerShell or Python might be good choices.... 

[katerina_newton]

Awesome, thanks again! I will dig into this when I get any downtime from my daily Canvas admin duties On a side note, is anyone familiar with this converter? JSON to CSV

It looks like a really easy way to produce a csv just by pasting JSON in the box (especially for beginners) and get a readable report literally in matter of seconds. Is it too good to be true?

[jblumberg]

Try this one:

http://jsonformatter.curiousconcept.com/

Cut & Paste the JSON data returned by Canvas.  Then delete by hand the following from the beginning of that data:

while(1);

The while(1); is not part of JSON...  it is added as a security measure (don't worry about the why... just delete it to look at the data).

Josh

Please note, you cannot just pass in the URL and expect it work since the website can't access your Canvas account.  While you could pass the token with the URL, DON'T do this!  It is a big security risk to trust your secret token with a remote site.

[BKINNEY]

Better yet, just stick

/doc/api/live after your instructure domain url (e.g. example.instructure.com/doc/api/live), and away you go. I only just learned that trick today. It may only work on instructure hosted instances. I'd be interested to know. Have a token on your clipboard when you go. Gets you as far as the JSON. After that, you'll still need something to parse it all out.

[stelpstra]

Try the Canvas Live API, which is very powerful: https://yourinstitution.instructure.com/doc/api/live

[stelpstra]

Oeps, it already has been mentioned...

[BKINNEY]

I have a developer key, and I'm trying to nail down my workflow for collecting/updating tokens. One thing I am doing is testing the validity of an existing token so that I can initiate a new token request if the one in my db has expired or been deleted. I couldn't find any direct way to do this, so I am making a GET request, and looking to see if it fails. When I initially set this up, I was getting a return array with $response['status']="unauthorized" or "unauthenticated" when the token failed. At some point, that changed, and now I have to look for $response['errors'][0]['message']=="Invalid access token."

So, I guess my question is, what is the preferred way to test a token? Is there something I can count on not to change out from under me in the future? If it matters, I'm using PHP and cURL.

[kenneth_larsen]

Hi  @BKINNEY ​,

As far as I know there is not a preferred way to test a token. I also use PHP and cURL and have followed a similar course to verify tokens. I typically use this functionality in course level LTI tools. After launch I run a basic GET request to get information about the course. One of the only differences that I use is that I look for the existence of ['errors'][0]['message'] not really looking at the specific message text. I have used that method for the last year or so and have not had any issues with changes.

Hopefully that helps.

[BKINNEY]

Actually, it does help, especially the part about it working for over a

year! Thanks.

Becky Kinney

Academic Technology Services

Project Blog <http://sites.udel.edu/bkinney/>

On Thu, May 14, 2015 at 12:33 PM, Kenneth Larsen <instructure@jiveon.com>

[hagimotk]

Hi Becky,

I don't check the error message content either, but here's what I do to check the validity of the tokens we store locally, according to this doc: Canvas LMS REST API Documentation (See the paragraph under "Storing Tokens".)  I make a GET call and look in the HEADER.  If the status is "401" and WWW-Authenticate is set (not blank, when status is 200, you don't get WWW-Authenticate), then I go ahead and re-get the user's access_token to store.  (This is what I get in the header, when token is invalid:

Status=401 Unauthorized, WWW-Authenticate=Bearer realm="canvas-lms", but I still just check that I get a non-null/non-blank WWW-Authenticate.)

We've only had our tools running for about three months since we're relatively new using Canvas, but this has been working for us.   If anyone has corrections or better ways to validate access_tokens, I'd love to know, too!

Thanks,

Kumi

[jhugon]

Hi Scott,

I am developing a Ruby on Rails app for the creation and curation of math problems (LaTeX, Desmos graphs), and trying to wrap my head around using the API to interact with our Canvas instance to create quizzes, etc. I am new to this group, so please let me know if there are threads I should read before reinventing the wheel here. A few questions to get started:

(1) Which rubygem is recommended for interfacing with the Canvas API? My plan is to use pandarus (instructure/pandarus · GitHub ) but I am open to suggestions. I also started tinkering with canvas-api (whitmer/canvas-api · GitHub ).

(2) Assuming that pandarus is the way to go, it appears to me that the gem requires knowing a user's access token in order to use the API calls (which makes perfect sense).

client = Pandarus::Client.new(

  prefix: "https://pandamonium.instructure.com/api",

  token: "[YOUR API TOKEN HERE]")

But what is the interface to first retrieve the user token given the app's "client_id" and "secret"? Does pandarus provide an interface for this, or should I use something like httparty for the so-called "OAuth dance"?

(3) In terms of the API itself, how can I link or embed a picture/graph within a quiz question? I see that the API allows for creation of questions and answers, and the uploading of files. But how can I then link the two from my app? I could not find an option in the doc to do this.

(4) Related to the question above, is it possible to embed/link graphs in answers as opposed to questions? We would like to have math problems offer graphs as solutions.

Hope these questions make sense. Apologies in advance if these are really noob'ish, but I am just getting started with the API work.

Best,

-Jacques

[scottdennis]

Hello Jacques,

I am indeed the one who started this thread but regret to inform you that I don't personally have the technical know-how to adequately respond to your questions.  Hopefully some of the others who have been active in this group, like  @kenneth_larsen ​,  @travis_thurston ​, or  @karl ​, will know better than I.

Thanks,

SD

[jhugon]

Thanks, Scott. No worries. If you or others happen to know of threads or examples that illustrate the use of the API and Pandarus, I would appreciate it.

Cheers,

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Jacques Hugon

Instructor, Math and Computer Science

Phillips Academy, Andover

jhugon@andover.edu<mailto:jhugon@andover.edu>

P: 781.899.4939

C: 781.249.3421

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[kenneth_larsen]

Hi Deactivated user​,

Sadly I am not going to be much help with your Ruby questions due to the fact that all of my Canvas API development experience is through PHP and learning Ruby is still an item on my goal list. But I might be able to offer some suggestions with the others. As a quick disclaimer, I only briefly played with the quiz API two years ago (when I was starting to learn the API) and it is easily the most complex and involved APIs I have ever tried to use (and all I was trying to do was to duplicate an existing quiz). With that said let's look at your other questions:

Question 3

In order to embed an image in a test question you will probably need to do something like the following:

1. Upload the image
   • When the image is uploaded it is placed in a queue and the API will response will include a "status_url" that you will need to ping until you get an "upload_status" of "ready".
   • When you get the "ready" response you can then get the ID of the file
   • Alternatively you could use list the files for a given course, user, group or folder and retrieve the ID that way.
2. Create the question
   • The question text should accept html so for the image you will need to write something like
     <img src="/courses/{course_id}/files/{file_id}/preview" alt="Something describing the image" />
   • The {course_id} will match the course you are loading the image into and the {file_id} is what you retrieved in step 1
   • Alternatively you could host the images elsewhere and just add a link to that external image, just make sure it is secure so that browsers won't block it (https).

Question 4

Based on Canvas' built in method for creating quizzes, I am pretty sure that the answers can only contain text.

Hopefully this helps

[jhugon]

Thanks, Ken. Your suggestions for question 3 make great sense. I had missed the fact that I could embed an image “preview” pointing to a local file in the HTML. Given that the pictures are already stored in an online database with unique secure URLs, your suggestion to simply include a link to these images may be easier to implement (and DRYer as well) than uploading the files for each quiz in each section of each course.

Question 4: Thanks, I expected this was the case.

Much appreciated!

Cheers,

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Jacques Hugon

Instructor, Math and Computer Science

Phillips Academy, Andover

jhugon@andover.edu<mailto:jhugon@andover.edu>

P: 781.899.4939

C: 781.249.3421

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[BKINNEY]

Canvas answers have been upgraded to permit html. I've tested it, and images work fine. There is a tricky bit when pulling questions out of the API, though, and presumably also when pushing them in. The documentation says that answer-specific feedback will be provided in the answer array as ['comments'], but new question feedback is now coming in as ['comments_html']. Answers themselves might be found in ['text'] or in ['html'], so you need to check both. In general, it is a good idea to triple-check the results of an API call rather than trust the documentation. Even endpoints that are not in beta are not entirely stable. That's not too surprising given the rate at which Instructure is pushing Canvas forward. Still, it would be a huge help to me if the documentation would keep pace, and better still if there were a mailing list that consistently notified developers every time the API changes.

[ordwaye]

I have used both quite a bit for automation.  I do course setup and enrollment management with them.  I have moved everything over to pandarus as it seems a bit cleaner.  You seem to be looking to use it for user interaction which I have not done so I can not help you much.

[owen]

What's the best way to let Instructure know about a bug (or something that appears to me to be a bug) in the API?  I have been experimenting with creating quizzes, which means using parts of the API that are still in beta.  I want to report bugs as I find them, not because I expect them to be fixed right away but just in case the information is helpful to developers.

I've submitted a few tickets through the general Canvas help center, but that means extra work for the admin people at my institution (who filter tickets so that Instructure only gets what seem like genuine errors).  It seems like it would create extra work for Instructure also, although I don't really know how many steps are involved in getting from support techs to developers.

[kona]

That's a good question. We've been doing the same thing as you - IT person submits a ticket, I escalate it, Canvas support takes a look, and hopefully escalates it to the right person/people - but if there is a better or more efficient way of doing things we'd be happy to do it!

[scottdennis]

Hi owen​ and  @kona ​,

Filing a ticket and escalating it really is the most efficient process.  You are correct; it does mean work for everybody but that is the best way to get an issue or a bug into the tracking system so our engineers can address it.

[BKINNEY]

I just learned the most amazing thing, right here in the community, but hidden away in a questions page.  I'm thinking we should have a place to collect a list of undocumented admin/developer gems. Ever hear of /undelete? Do you know of others?

[mcarruth]

I am using PHP cUrl  with the Canvas API to create quizzes and add quiz questions.  Canvas LMS REST API Documentation  shows the API call necessary for question creation. Creating the question works as long as I do not include an answer.  The API requires question[answers] with [Answer] as in input. I have tried multiple arrays with various names for the keys.  Does anyone have a working example of adding a quiz question with answer, or adding an answer to an existing question?

[dogwynn1]

If you figure out how to add a question with an answer, let me know. I'm still trying to figure it out myself. I'm using Python3 with urllib, and I keep running into inscrutable error 500s when I try to POST or PUT updates to existing answers. I'm somewhat convinced its an encoding error, but encoding a list of dictionaries in x-www-form-urlencoded is not so straightforward. Very frustrating, given that the whole point is to be able to create actual quizzes with answers.

It almost seems like there needs to be another API level for answers in a question (similar to questions in a quiz).

[ordwaye]

You might try exercising it via the live api on you test site.  your.site/doc/api/live  I have found it useful for test out my expectations.

[dogwynn1]

Thanks for the response and the helpful advice!

However, I think this functionality is deliberately missing from the current beta: https://community.canvaslms.com/ideas/2348#comment-17326

[mcarruth]

I chased this rabbbit for several days and finally sent a ticket to Canvas Support.   the final answer was, BETA not working

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

I chose to build XML files and zip as a QTI package and then run a content migration with the Canvas API.  This solution will build quizzes with questions, even random number of questions.

[dogwynn1]

Thanks for the response. Unfortunately, given that so many fully working API endpoints have that warning, it's a bit like "crying wolf"; you just stop seeing it.

I'll definitely look into your solution. Thanks much for pointing it out.

[ordwaye]

I use the api via the Pandurus gem.  Based on a faculty request feed from another app I use content migrate to pull in a template course.  This is then completed by creating modules for the varying number of weeks.  Some of the pages also have their content modified by pulling them and doing a regex for things like course and faculty names.  Since our enrollment feed does not include course drops I use the api to compare the courses section enrollments with the actual enrollment data. That data is used to generate an SIS file to conclude the students that have left the course.  Since that last one is a bit api intensive it only runs once a day.  I also use the api to upload the hourly full SIS package that is created by the app.

[jason_gwartz]

Hi all! I work at the London campus of Hult International Business School. We've developed a small command-line utility to automate a few tasks in Canvas, especially when dealing with groups. We'd love to share it with other institutions or get some feedback from developers about it!

https://github.com/jasongwartz/CanvasHelper

Now we have the professors fill out a simple spreadsheet and use this tool to create all the student groups in a course automatically. It's saved us countless hours from dragging-and-dropping the students into groups.

Please let me know if you think it'd be useful at your school, or if you're a Python programmer and would like to help contribute!

[scottdennis]

Thank you for sharing,  @jason_gwartz ​!

[glparker]

I'm going through the process to migrate our users from the legacy Respondus Lockdown Browser integration to their newer LTI integration.   As part of this, I want to know which courses have quizzes protected by Lockdown Browser (legacy version), so I can work with those faculty on the changes.

I can see where /Assignments know about Turnitin Settings, but I've not yet found similar API data on Lockdown Browser.   Does it exist via API, if so, where?  Can the API tell me if a quiz is configured to use Respondus Lockdown Browser?

Thanks, Glen

[kenneth_larsen]

 @glparker ​,

If you use the Quizzes API to list all quizzes for a course (or if you get a single quiz), there are several items that pertain to the lockdown browser. They are not listed in the documentation but they should be there:

"require_lockdown_browser": true,

"require_lockdown_browser_for_results": true,

"require_lockdown_browser_monitor": null,

"lockdown_browser_monitor_data": null,

[ldprogrammers]

I really wished that the create APIs would offer the same fields that you get if you do a get.  lol

I just discovered that the POST course module does not include the publish state.  I've created and ideal but really do not have a lot of faith in the enhancement request process for developer wants/needs as there are many more users who want nice pretty things over backend needs. 

We want to create our modules in a published state to help with scalability.

[scottdennis]

I think your concern is valid.  We are evaluating various options for balancing feedback from front end users, back end developers, mobile users, K12 vs Higher Ed, etc.

[mcarruth]

I create and publish modules frequently.

Creating a module and publishing a module is a two step process.

Create use endpoint

POST /api/v1/courses/:course_id/modules

To publish  a module use

PUT /api/v1/courses/:course_id/modules/:id

[jpgorrono]

My tidbit is ...

I've been using curl to call the api's when trying things out and the python json.tool module is very useful in that it formats the call results:

curl -v "https://canvas.test.instructure.com/api/v1/users/self/activity_stream \

-H "Authorization: Bearer `cat sis@canvas`" | pyhton -mjson.tool

If the result is json it is nice formatted: not all on one line.