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.

[maguire]

I made a simple python program to get information about both users and students in a course with the output formatted as a spreadsheet (.xlsx). One of the features of this program was to get the various communication channels associated with each person. Adding and removing Twitter as a registered service revealed that there is a need for a third value ('inactive') for the "workflow state" associated with a communication channel. For details can code see List of users and students in a course: Chip sandbox

Note that the program could be split into a list users program and a list students program, but this example of using the API was relatively simple and illustrates the power of the API.

[jhlieth]

When I try to get a list of my courses using the get URL: ...api/v2/courses I get only 10 of my courses.

I have read the documentation for this call a dozen times and cannot spot where it hints that this is the expected behavior for this call.

I see this with browsers but also when I try to use VBA coding. It is a problem because the most important courses for me are not in the returned list.

I have many more courses on the books (the Canvas GUI lists 26 which are currently relevant).

What do I have to do to get ALL my courses for the current quarter.

What would the URL look like to get all the current and future courses where I have at least one student enrolled?

EDITING to Add: I posted the above without realizing that there were already 8 pages in this thread. (I am relatively new to Canvas and very new to this Forum)

On one of the earlier pages in this thread I learned that pagination is used for some calls  It appears that the documentation is failing to identify that paging is needed for this. Perhaps this could be added.

If I run into other API calls were paging is needed, how do I know this is happening. In other words, how do I know that when I make the call as documented, that the returned data is paginated? I have been making API calls and staring at JSON responses all day (with VBA in Excel) and noticed nothing that would give me a hint to this.  I did now find the documentation on Pagination but do not understand it; what and where is the Link header? I do see a vague hint on that page that I could pass the a parameter to force the page size to some "unspecified number". What is the syntax for that?

[maguire]

There is an example of handling the paginated response at Listing your courses and paginated responses: Chip sandbox  

The magic is the line:

while r.links['current']['url'] != r.links['last']['url']:  

which checks if the response's link header (a HTTP header in the response) has a last URL that that matches the current page's URL. 

[garth]

 @jhlieth ‌ , following up on what  @maguire  has pointed you, you might also look at this document:  

• Pagination - Canvas LMS REST API Documentation 

there is a variable that allows you to define the number of results you get per request: "per_page"

the defuault is 10, but you can reduce the number of api calls you have to make by increasing this number.

i use a default of 100 results.

[jhlieth]

I have been trying to wrap my head around this. In a Browser I can put in /api/v1/courses?per_page=1000 and I see that this seems to work to get all 26 courses. I purpose used such large number to avoid having to write pagination code as that would eat a few hours of my time. In my Visual Basic for Applications (VBA) project am using:

...

 Dim Hreq As New WinHttpRequest

...

 Hreq.Open "GET", URL, False
 Hreq.Send
 ResultStr = Hreq.ResponseText
 ResultHdr = Hreq.GetAllResponseHeaders

...

So that the last code line lets me inspect the header programmatically and I do find the Links there. But I see that when I use 1000 that it pages per 100. Perhaps 100 is the max allowed?

[kenneth_larsen]

In my experience, 100 is the highest Canvas will return per page.

[garth]

haven't tried any more than that, thanks : )

[garth]

 @jhlieth ‌ if i were you, i would invest the few hours and implement logic around pagination, it is the only way to guarantee you always get ALL results from any request.  if you don't implement pagination, you could easily find yourself scratching your head wondering why you aren't getting everything.

just my 2 cents

[maguire]

You will need something like:

    ResultLinks = Hreq.GetResponseHeader("Link")

then parse the resulting string (after a split on ";") for the current and last URLs, compare them; if not equal then loop with next URL

[maguire]

To clarify what Garth has said, I modified my earlier program to pass the additional parameter.  See Listing your courses and paginated responses - more per page: Chip sandbox 

I should note that there are some places in the Canvas user interface where the paginated responses are improperly handled by Canvas, see for example Changing limit on the number of custom columns shown by the GUI The result is that you do not get more than 10 custom columns shown in the gradebook even when there are more custom columns. (I'm still awaiting a response from someone at Instructure.com about this error.)

[sam_dickerman]

Hello:

I hope I am posting this question in the right place...

In the fall of 2015 I was trying to develop my own speedgrader for open response quiz questions when I discovered that the quiz API was not working as documented.  This long process is covered in this thread that included Deactivated user,  @James  and some key help from wfrakes.  

In the end Jason Sparks said:

This is a very innovative use of the API.  The current API remains in a beta stage as we are actively considering some new development on the quizzes front. For now there will not be any further development of the current API. We will share more in the near future as things progress.

17 months later I thought I would check back and see if any progress has been made.  However, the documentation does NOT seem to have been updated - so the broken API calls and misleading examples (see my explanation) are still there.

Nevertheless, hope springs eternal and I wanted to see if someone from Instructure could provide an update.

Fingers crossed,

Sam Dickerman

Brookline High School

[mgohman]

Hello Everyone, 

Building my first API - trying to pull the current user's first and last name for a printable certificate.

When I put the following url in a browser, it returns what I am looking for.

https://msmu.instructure.com/api/v1/users/self/profile 

The above does not require my access token when used in the browser's address bar. But when I try and use PHP cURL it asks me to authenticate to pull that same URL. When I try and use our access token - it does not return the current user logged in, but rather my API user profile.

How do I use PHP cURL to get the current user's profile credential without authenticating?

Scoured the online documentation and sample scripts from Google without any luck. Thanks in advance for pointing me in the right direction.

Cheers,
Mitch Gohman

[themidiman]

I believe the answer is to form a GET request with the user ID in the URL endpoint

GET /api/v1/users/:user_id/profile

Users - Canvas LMS REST API Documentation 

[themidiman]

Oops forgot to mention that there's no way to get this information without being an authenticated user with proper permissions. You'd have to send an API token in the request. 

[ordwaye]

You can also play with the api at Canvas Live API 

[garth]

 @mgohman ‌ the api call you listed contains the parameter "self"

https://msmu.instructure.com/api/v1/users/self/profile 

To quote the Canvas API documentation:

"Throughout this API, the :user_id parameter can be replaced with self as a shortcut for the id of the user accessing the API. For instance, users/:user_id/page_views can be accessed as users/self/page_viewsto access the current user's page views."

If you are logged in, you are the current user.

Take a look at the definition of the profile API call, it shows that it accepts the parameter of ":user_id":

• Users - Get user profile

You would need to pass the user id of the student you are trying to get information on.

You would also need necessary privileges to access that user profile, and I'm not sure what your role is. 

From your post, it sounds as though you are trying to get information about students in a course.

If you are an instructor in the course you should be able to access your student roster, which also contains names, using this API call:

• Courses - List users in a course

This API call returns a list of "User" objects:

• Users - User object 

In response to your statement:  "The above does not require my access token when used in the browser's address bar", this is because you are already logged in with the browser.  You absolutely need to use your own token when making API calls outside of the browser.  If you need info on creating an access token, see this article:

• How do I obtain an API access token for an account? 

If you would like more information on how to test and play around with API calls this post might be helpful:

• API Testing: Postman 

I hope that helps.

[mgohman]

Thank you Garth!!  I think we are getting closer.

I saw the passing of the userID, but I am having trouble figuring out how to get the userID. Right now, my API application resides on a separate server (msmu.us)- not on our Canvas installation (msmu.instructure.com). Ultimately I would like to access the currently logged in user to get their details (already logged in through msmu.instructure.com).

I was successful in obtaining all of the students in the course, and passing an individual ID like the documentation says. But I need a way to tell which student is currently accessing the course. I think from what you are saying that this is not possible. That I would have to have them log into my application (using their Canvas Creds). Then I can do things for them specifically.

I would love it if the user only had to log into the main Canvas App once. And then my extended application would leverage this Canvas App login to perform user specific needs. Is this possible?

Or do I need to develop it as an LTI/Plugin in order to do this? Kind of like the Attendance App in Canvas, where it asks for permissions first.  And it actually resides directly in Canvas, instead of an iFrame (which was my original goal) or a separate stand-alone website.

Thanks for all of your assistance and pointing me in the right direction.

Cheers,
Mitch Gohman

[ordwaye]

If you know their sis id you can pass that in the form of 'sis_user_id:A000030483' . 

[garth]

 @mgohman ‌ LTI would definitely tell you who the user is that is accessing your application.

I put together a 3 part LTI intro walk through that will help you get started in that direction.

Part1 is here: .NET LTI Project - Part 1 - Connect to Canvas 

I also put together a list of helpful LTI resources:  LTI 1.x - Useful Links 

If you go the LTI route, take a look at these variables:

• custom_canvas_user_id - this will give you the numeric Canvas user id
• custom_canvas_user_login_id - this will give you the user login name
• lis_person_name_full - is what is says, the user full name

There is lots of info in the LTI launch request, should be everything you need to clearly identify the user, and if course specific will clearly identify the course they are launching your app from.

I'm currently working on extending the LTI posts to include the OAuth2 workflow, and have the first piece posted here:

.NET - OAuth2 Workflow: Part 1 

Hopefully these references will be of some help, I'm working on part 2 of the OAuth2 example now and hope to have it posted soon (time permitting : )

Post back and let us know what direction you go in.

[mgohman]

Got it, that is very helpful. Thank you for everything!!

Cheers,

Mitch

[rlzhang]

First you need have your authorized user's access token. then in php, pass in your authorized tokenHeader, and pass as_user_id parameter to masquerade the userid who you are authorized to access the profile.  e.g.

$asuser = array ('as_user_id' => $userid);
$user = http_build_query($asuser, '', '&');

...

curl_setopt($ch, CURLOPT_URL, $canvasapiUrl' . '?'. $user);

Hopefully it helps.

[keith3]

Hey, as a part of a product requirement I need to add a link in each Canvas course to a predefined URL. In order to do so, I'm using the `external_tools` API in order to create them. I pass different values in the course_navigation param and a button is created at the bottom of the left navbar in the course navigation page. I'd like to place this button at the beginning of this navbar or, if it not possible, create the button in the left navbar of the course navigation (I've tried using the course_home_sub_navigation param but It didn't work). Any ideas? Thanks. Here is the doc I've been reading: External Tools - Canvas LMS REST API Documentation 

[raul_pineda]

Hello Everyone! I'm very new to APIs as well but I was wondering if It was possible to transfer grades from one course to another using an API? If so any tips on how to approach this?

[maguire]

@ @raul_pineda  You can certainly get the grades out of the gradebook with the API:

   GET /api/v1/courses/:course_id/gradebook_history/feed

and you can insert grades for assignments (in the new course) with the API (I'll thanks @pklove for his posting Grade Change in Canvas API 😞

   PUT /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id

You can see the whole process with some examples at https://kth.test.instructure.com/courses/11/pages/programs-related-to-assignments-and-their-grades 

Your question was well timed, as I am just in the process of looking at how to bring over grades from another record system into Canvas (as students have done part of the requirements for courses prior to our introduction of Canvas) as our LMS. My hope is that moving the grades into the Canvas course will facilitate helping students to complete the remaining requirements of the course and hence finishing the whole course. You question prompted me to write my new tool: assign_grade_for_assignment.py course_id assignment_id user_id grade [comment]

[maguire]

The correct URL to use is: Programs related to assignments and their grades: Chip sandbox 

as the one to the test environment will disappear (at some point).

[walter_yuan]

The create assignment API

POST /api/v1/courses/:course_id/assignments

seems to create two duplicate assignments (instead of one) every time I call it. Has anyone else experienced this?

[Stef_retired]

Welcome to the Canvas Community,  @walter_yuan  Welcome! Walter has also posted this as a separate question, so if you can help, please add your responses to Create assignment API creating duplicates 

[philip_brands]

(with root-privileges)

`/api/v1/courses/sis_course_id:<sis_course_id>?include[]=sections`

always returns the course (just fine) with:

`...
, sections: [],
...`

(empty array...), where I would expect to get at least elementary information on a course's sections (sis-integrated and non-sis-integrated).

What am I doing wrong, or is this a bug?

[maguire]

I get the section information using GET /api/v1/courses/:course_id/sections and this seems to work. I get an array of JSON that looks like the following:

[{"id":10722,"course_id":yy,"name":"C's section","start_at":null,"end_at":null,"created_at":"2018-05-16T01:27:37Z","restrict_enrollments_to_section_dates":null,"nonxlist_course_id":null,"sis_section_id":null,"sis_course_id":"xxxx","integration_id":null},
{"id":10725,"course_id":yy,"name":"H\'s section","start_at":null,"end_at":null,"created_at":"2018-05-16T01:27:38Z","restrict_enrollments_to_section_dates":null,"nonxlist_course_id":null,"sis_section_id":null,"sis_course_id":"xxxx","integration_id":null},
{"id":10724,"course_id":yy,"name":"H\'s section for yr1","start_at":null,"end_at":null,"created_at":"2018-05-16T01:27:37Z","restrict_enrollments_to_section_dates":null,"nonxlist_course_id":null,"sis_section_id":null,"sis_course_id":"xxxx","integration_id":null},
{"id":10726,"course_id":yy,"name":"K\'s section","start_at":null,"end_at":null,"created_at":"2018-05-16T01:27:38Z","restrict_enrollments_to_section_dates":null,"nonxlist_course_id":null,"sis_section_id":null,"sis_course_id":"xxxx","integration_id":null},
{"id":10723,"course_id":yy,"name":"M\'s section","start_at":null,"end_at":null,"created_at":"2018-05-16T01:27:37Z","restrict_enrollments_to_section_dates":null,"nonxlist_course_id":null,"sis_section_id":null,"sis_course_id":"xxxx","integration_id":null},
{"id":11280,"course_id":yy,"name":"Mi\'s section","start_at":null,"end_at":null,"created_at":"2018-08-28T11:37:01Z","restrict_enrollments_to_section_dates":null,"nonxlist_course_id":null,"sis_section_id":null,"sis_course_id":"xxxx","integration_id":null},
{"id":8754,"course_id":yy,"name":"Section for the course xx","start_at":null,"end_at":null,"created_at":"2018-04-20T20:26:56Z","restrict_enrollments_to_section_dates":false,"nonxlist_course_id":null,"sis_section_id":"xxxx","sis_course_id":"xxxx","integration_id":null}]

[philip_brands]

Thanks Gerald,

I'm aware of the course/<course_id>/sections endpoint. In fact that is what we use at this moment. But wanting to minimize the number of requests our app does on the canvas-api, I was looking for a single call to get both the course and the section information.

[maguire]

Dear  @philip_brands ,

I looked at the code that is at lib/api/v1/course.rb that implements the course API, it first filters out whether the user making the call has the permissions to get the data and if so computes the sections as follows:

         hash['sections'] = section_enrollments_json(enrollments) if includes.include?('sections')

So if the include[] includes 'sections' then it calls section_enrollments_json(enrollments)

The code for this can be found in: lib/api/v1/section_enrollments.rb - where this code is simply:

module Api::V1::SectionEnrollments
   def section_enrollments_json(enrollments)
     enrollments.map do |enrollment|
        section = enrollment.course_section
        section_json = section.attributes.slice(*%w(id name start_at end_at))
        section_json[:enrollment_role] = enrollment.type
        section_json
        end
     end
end

According to Courses - Canvas LMS REST API Documentation  enrollements is "

// A list of enrollments linking the current user to the course

thus if the current user (the one calling the API) is not in the course, there will be no section information. Thus it is likely not your permissions, but rather this limitation based on enrollments that causes the section information to be [].

It would seem to be a conscious decision to limit the enrollment information, as even the List enrollments API notes: "note: Currently, only a root level admin user can return other users' enrollments. A user can, however, return his/her own enrollments."

[James]

 @philip_brands  

The API you're using is Get a single course. If I call this as someone who isn't in the course (for example our system integration user), then I get the empty array that you're getting. If I make the same call as someone who is enrolled in the course (for example, me for the course I'm teaching), then I get sections returned. It appears that the extra parameters are limited to the scope of the calling user. That might be hinted at in the note "Accepts the same include[] parameters as the list action plus:" The list courses is "list your courses" and is definitely scoped to the current user. I think I've ran into this before with the dates available for access being scoped to the user. When I contacted Canvas support, they said that was the intended behavior. Essentially, it's a way to get a single course for a user without having to get all of the courses for the user.

The List course sections endpoint that  @maguire  provided will get the sections even if you're not enrolled in the course. There are other ways to get a list of sections as well. For example, I grab the list of sections (with some other things I need) through the enrollments API.

[philip_brands]

Thanks for your research James, 

I was not aware of this limitation on this include[] parameter. I could have guessed, because there are other include[] params in the API that have similar permission restrictions. The basic philosophy behind those restrictions is somewhat obscure to me though.

If I understand correctly, I am not the user with root priveliges I claimed (and thought) to be then ... I'll go figure out what exactly I am to our Canvas API then 😉

P.S. found it:

I was testing this with our developer-key in Postman, which would indeed run into this not-a-course-user restriction.

Using our LTI-integration with my personal credentials (user with course enrollment or account/course-admin-user) will give the expected results.

[emanuela]

Hi there, I am new to Canvas and I'd like to use it for my organization. Before that I really need to know if there is a way for my developers to interact with Canvas' video player API (i.e. Will I be able to prevent my students to see the following video without having finished the previous? Will I be able to embed a script to launch a random pop-up that asks a student if he is still watching the video to test his attention?). To sum up I would like to know what is the level of personalization of your platform (of course I'd like to suscribe to the full account and not only to the free one). Please let me know  Best, Emanuela

[jblumberg]

 @emanuela ‌,

You should try to leverage the built in features in Canvas as much as possible before moving to custom development.  

1.  Canvas can limit progress using modules. So you can have students be unable to move forward until they view a resources, complete a quiz, etc...

2.  A built in method of assessing a video is to use a video as the description of a quiz... this way they watch the video and then take the quiz.  You can then allow multiple attempts.  I really like this method myself.

3.  You can embed an outside video tool that has pausing of videos with pop-up questions.  Instructure's product Arc may have the features you are looking for (Arc | A Better Video Platform for Better Online Learning ), or you may want to look at other toolsets (Camtasia and other products have these features) where you can simply embed the content.

4.  For our organization we often host the videos externally to canvas and embed the content (Vimeo, youtube, google drive, etc...).  This works for us well.

[emanuela]

Hi Josh, 

thank you for your kind reply. This was helpful, anyway I am gonna explain my situation in details so you can help me even more. We, as a company, would like to do courses for architects and engineers in our country (Italy), here to access the possibility to give our customers a special kind of certification at the completion of the course, the national organization of architects and engineers aks us for special requirements (like the ones I wrote above in the examples). So we are wondering if it is better for us to write our own website or if there is some sevice (like yours) that we can use but customizing the code tu fulfill the above-mentioned requirements. So, it is vital for me, in order to choose your service, to know if it would be possible for our developers to touch the code of the video-player in order to tailor it on our needs and also if your website give access to the log data of users (when they have seen each video, how many times etc).

Said that, I think that point 1 and 3 of your answer could be very helpful and I am gonna fully explore your tool Arc (even if I fear that it is only for live webinars) and this other Camtasia that you suggested.

Many many thanks for your assistance and patience,

regards,

Emanuela

[jblumberg]

 @emanuela ‌,

I don't work for Instructure.  I work for a small College that uses their product.  We don't use ARC so I don't know it's feature set well.

We have heavily customized Canvas in some cases to do the kinds of thing you ask for, so they seem very possible... with that said, it may or may not be your best solution.  You should engage with Canvas sales and get setup with a demo account if possible.  Some customizations (custom JavaScript and Custom CSS) you can't do with the free teacher account.

[emanuela]

Hi Josh, 

I am sorry I didn't know. Your feedback was really helpful anyway, I will do as you suggested!

Many thanks and kind regards,

Emanuela

[kenneth_larsen]

It's been awhile since I had an API question I wasn't able to figure out and forgot this thread existed so I posted a question about setting to do dates on assignment pages using the API that I will post here as well in case anyone has any insights.

Last Fall Canvas added the ability to set a date on pages so that they appear in the student to do list:

Unfortunately, there is no information about this functionality available in the Pages API.

I can view that date using the List pages or Show page API

I have tried the typical Update/create page api pattern for updating page information by passing wiki_page[todo_date] as a date similar to what I would do to update an assignment date, but that doesn't appear to do anything.

Anyone worked with this yet, or any of the awesome Canvas Engineers have any information on how to set this date through the API?

Thanks fo any insights!

[James]

I think I answered it in https://community.canvaslms.com/thread/32856-anyone-figured-out-how-to-set-a-page-to-do-date-through... . It's student_todo_at instead of todo_at.