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.

[jpgorrono]

Stan,

That url path doesn't look right... looks like your are PUT'ing to the api playground location in docs

should be '/api/v1/courses....'  afaik

[test]

Hi,

I would like to ask for a tiny addition to the enrollments end point (api/v1/courses/xxx/enrollments)

When getting list of enrollments for a course/course section, in the user section (highlighted below), the user email address is missing.

For us to get the user's email address, we need to make another call to the PROFILE end point.

Would it be possible to add user's primary email address to the user info so we save another call?

{"id":17452826,"user_id":3797794,"course_id":832406,"type":"StudentEnrollment","created_at":"2013-01-15T20:06:39Z","updated_at":"2016-04-11T13:38:19Z","associated_user_id":null,"start_at":null,"end_at":null,"course_section_id":889149,"root_account_id":97951,"limit_privileges_to_course_section":false,"enrollment_state":"active","role":"StudentEnrollment","role_id":2441,"last_activity_at":"2015-03-06T13:59:26Z","total_activity_time":5060,"sis_import_id":null,"grades":{"html_url":"https://evaluationkit.instructure.com/courses/832406/grades/3797794","current_score":null,"final_score":0,"current_grade":null,"final_grade":null},"sis_source_id":null,"sis_course_id":null,"course_integration_id":null,"sis_section_id":null,"section_integration_id":null,"html_url":"https://evaluationkit.instructure.com/courses/832406/users/3797794",

"user":{"id":3797794,"name":"Student 1","sortable_name":"1, Student","short_name":"Student 1","login_id":"student1@evaluationkit.com"}},

Thanks,

Matt.

[MattHanes]

Greetings Matt,

You may have more luck to see your proposed change happen if you were to use the Canvas Feature Ideas​ space.

[BKINNEY]

It's already there. Just add include[]=email to the endpoint.

Becky Kinney

Academic Technology Services

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

On Thu, Apr 21, 2016 at 3:11 PM, Hanes.Matthew.B@muscogee.k12.ga.us <

[test]

It didn't work.

Thanks,

Matt.

[BKINNEY]

Matt,

I don't know if you are still working on this, but here is the address that works for me.

/api/v1/courses/####/users?enrollment_type=student&include[]=email

I'm not sure what the difference is between the users endpoint and the enrollments one, hopefully it isn't that users is deprecated! Anyway, this works for me today, and has been for a couple of years now.

[lorne_olfman]

How can I get user id from the access token?

[jpgorrono]

 @lorne_olfman ​

This is one way:

export PYTHONIOENCODING=utf8; curl -s https\://<server.your.domain>/api/v1/users/self?access_token=<user's_token> | \

python -c "import sys, json; print json.load(sys.stdin)['id']"

[lorne_olfman]

JP:

Thank you very much!

Lorne

[louizhu]

I am new to Canvas API. I use PHP and curl to interact with the API. I am writing some code that can grade and comment assignment submissions using the Submission API. I have figured out how to PUT or POST single or multiple grades and comments. What I haven't figured out is how to modify an existing comment. Submitting a new grade will overwrite the existing one; however submitting a new comment will just add the new comment. The Submission API does not have a method to delete a comment or grade. Any help would be greatly appreciated.

Louie

[ordwaye]

I am pretty sure that you can not edit existing comments.  That would allow someone to rewrite the history of the submission.

[louizhu]

Is there a way to remove an existing comment through API? I know in Canvas I can not edit a comment, but can delete one. 

[kenneth_larsen]

 @louizhu ​, I did some digging through the API and I am not aware of a way to delete submission comments. That isn't to say that it is not possible, just that if the way exists, I don't think it is documented. I would be happy if someone could provide information to the contrary.

[louizhu]

Thank you very much, Kenneth. I'll keep trying. If I find something useful, I'll update here.

[garth]

For those few of us out there working with .NET, I have published a starter project implementing the API in C#.

It is meant as just that, a starter project, that can be easily modified.

I have created a workflow service to automate many admin tasks and reports associated with our instance of Canvas, and this starter project is essentially the base.  Once you know how to make the calls using .NET, you can wrap the API calls in your business logic to meet your specific goals.

• .NET - Canvas API Implementation

Hopefully this will be helpful.

[mark5]

I am new to the Canvas API offerings and this may not even be the correct forum, but here goes.

I have a use case where I need to capture an event in the Canvas web UI (instructor adding person to course) and have that event trigger an API external to Canvas. The Canvas APIs are great for events inbound to Canvas but I have not found a solution that would allow me to trigger events outbound. An LTI enabled tool provider seems like a possible solution but that would require the instructor to alter their workflow.

Are there any options to capture web UI events and have them trigger an external REST API?

Thanks for your consideration...

[BKINNEY]

Mark,

I don't know how much help this will be, but for what it's worth, you can trigger client-side actions based on user events by adding custom js to your Canvas account or sub-account. If your third party API requires authentication I don't know how much good it will do you, but you can take advantage of the fact that jQuery is already available in a Canvas page, so with just a minor js tweak, you can get a Canvas page to do pretty much anything a browser can do.

HTH

[mark5]

Becky,

The API does need some form of authentication/authorization. However, your suggestion to look at custom javascript is interesting. I will see where that leads me.

Thanks,

Mark

[louizhu]

I need some help with grading group assignments. I am currently using the Submission API and the following request

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/update_grades

to grade individual assignments and it has been working well. I was trying to use the same method to grade group assignments. For the parameters, I replaced the <student_id> with the <group_id> and I set "group_comment" to true. However, I have had no luck so far. I did not get any error, but grades and comments were not posted either. If you have any experience with grading group assignments, please share. Thank you.

[marc_mestre]

Hello all,

Just sharing a bit of PHP code that can interact with the Canvas API without needing curl (if for whatever reason you don't have, or can't use the library).

The GET function includes logic that can deal with the Canvas API item return limit.

The POST function just requires a correctly formed array to post and you're good to go!

Make sure to set up a constant called TOKEN (this should be set to your current auth token). Or you could just edit the code and input it manually or with a variable/config file.

GitHub - MarcLightning/canvasUtils: A small set of scripts that interface with the Canvas REST API (...

[maguire]

There is an error in the documentation for https://canvas.instructure.com/doc/api/peer_reviews.html

Peer Reviews - Canvas LMS REST API Documentation

as there are two sections entitled "Create Peer Review"

The second of these is about deleting a peer review.

It is unclear how one can use the API to assign a peer reviewer.

[garth]

To create a peer review you would use the "POST" call.

I will admit I have not personally tested this specific API call.

[maguire]

The POST API in the form:

https://xyz.test.instructure.com:443/api/v1/courses/:course_id/assignments/:assignment_id/submission...

does not work, it returns:

{
  "errors": [
  {
  "message": "The specified resource does not exist."
  }
  ],
  "error_report_id": 82505
}

Response Code

404

Interestingly the GUI to assign a reviewer is using a form action with a URI of the form:

/courses/:course_id/assignments/:assignment_id/peer_reviews/users/:user_id

Where user_id is the assessor and it is passing the reviewee_id as an argument.

If I use the GUI to assign the user, then I can use the API to get the assigned user:

[ { "id": 2833, "user_id": xxx, "asset_id": 60033, "asset_type": "Submission", "workflow_state": "assigned", "assessor_id": yyy, "user": { "id": xxx, "display_name": "xx", "avatar_image_url": "xxxxxx", "html_url": "https://xyz.test.instructure.com/courses/CC/users/xxx" }, "assessor": { "id": yyy, "display_name": "Gerald Q. Maguire Jr.", "avatar_image_url": "yyyyy", "html_url": "https://xyz.test.instructure.com/courses/CC/users/yyy } } ]

Also note that I cannot delete this peer review assignment with the DELETE API:

https://xyz.test.instructure.com:443/api/v1/courses/CC/assignments/A_ID/submissions/xxx/peer_reviews...

{ "errors": [ { "message": "The specified resource does not exist." } ], "error_report_id": 82506 }

Response Code

404

[garth]

"The specified resource does not exist."

I have received this response in the past when I was using an incorrect resource id, i.e. the wrong assignment id, or the wrong course id, etc.

[rlzhang]

Hello all,

Question regarding to upload new file;

We are to upload some report file to user's File.  I called Canvas uploadfile API passing the file parameters via guideline Uploading Files - Canvas LMS REST API Documentation .   The file was uploaded correctly, but uploaded in the user's default File foder 'unfiled' instead of creating a new folder I defined in 'parent_folder_path' parameter passing in API call,  It used to work correctly creating and uploading the file in a new folder specified in 'parent_folder_path'.    Anyone has idea or experience using the uploadingfile api recently?   

Thanks in advance,

Ruiling

[kenneth_larsen]

 @rlzhang ,

I remember dealing with the same thing. When working with the user files you need to add an additional folder level.

parent_folder_path=my_files/

then put in the folder name that you want. That change took place a few months back and I don't know that it was ever documented. I figured it out the hard way.

Good luck!

[rlzhang]

Thanks Kenneth for your reply.  

I tried both add "my_files" or "./my_files" to  parent_folder_path parameter like below. but the file still pulled the file in default "unfiled" folder but not creating new "testfolder" .  Is it "my_files" a static foldername?  Thanks!

array(4) {

  'name' =>

  string(50) "mytestfile.pdf"

  'size' =>

  int(228394)

  'parent_folder_path' =>

  string(20) "my_files/testfolder"

  'content_type' =>

  string(15) "application/pdf"

}

[kenneth_larsen]

When you are looking at the user's files, you see a folder for the different courses they are enrolled in and in that list there is a "my_files" folder. Your "testfolder" should be inside that folder with the file in it. In my use case I am using a folder called "images" and this is what it ends up looking like:

[rlzhang]

Thanks Kenneth,  We have similar file structure as yours, but we don't have sub_folder 'my_files'.  but even though I manually add the folder 'my_files' under root folder My Files, then pass in the parent_folder_path="my_files/test".   after uploadfile api call, the new folder 'unfiled' is created, and the file is uploaded in 'unfiled' folder, while not in the expected my_files folder.

Here below is the cUrl I used to call the API:

$ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, $url );  //url for api/v1/users/{id}/files

        curl_setopt ($ch, CURLOPT_HTTPHEADER, $tokenHeader);//Authorization

        curl_setopt($ch, CURLOPT_POST, count($fields));   // TRUE

        curl_setopt($ch, CURLOPT_POSTFIELDS, $step1_params);

//step1_params :name=test.pdf&amp;size=228394&amp;parent_folder_path=test&amp;content_type=application%2Fpdf"

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // capture the response to a variable

        $response = curl_exec($ch);

        curl_close($ch);

What does the upload_params look like in your uploadfile api call response?   One place I noted in the upload_params on my response, the key is indicated under ../attachments/,  but canvas API document give sample response result as ""key": ".../files/testfile". but not sure if related.   

array(9) {

  'AWSAccessKeyId' =>string(20) "testid"

  'Filename' => string(50) "test.pdf"

  'key' =>string(96) "account_45110000000000001/attachments/2308001/test.pdf"

...}

Thanks!

Ruiling

[cdeville]

Here is some undocumented behavior I have noticed with the File Uploads API and the 'unfiled' folder. I used the following parameters:

on_duplicate: 'overwrite'
parent_folder_id: 'sample id goes here'

If the file I attempt to upload is identical to the file in the target folder, it will create or update a file in the 'unfiled' folder. I don't mean identical in name alone, I mean if the file content and the file name is identical. As soon as I attempt to upload a file that is identical in name, but not identical in content, the API updates and overwrites the target file in the target folder as expected.

It is already documented (see below) and understood that if the file I attempt to upload has the same name as a file in the target folder, it will overwrite the target folder's file. The 'unfiled' folder appears to be completely undocumented. Also note that 'overwrite' is the default value if you don't specify.

From File Uploads documentation ( Uploading Files - Canvas LMS REST API Documentation 😞
on_duplicate
How to handle duplicate filenames. If `overwrite`, then this file upload will overwrite any other file in the folder with the same name. If `rename`, then this file will be renamed if another file in the folder exists with the given name. If no parameter is given, the default is `overwrite`. This doesn't apply to file uploads in a context that doesn't have folders.

Hope this helps, I know it took me way too long to figure this out.

[garth]

Did you make the call to get the sub-folder id?

• Files - List all folders

[rlzhang]

No Garth.  I didn't pass sub folder id,  my understanding  the passing parent_folder_path would created if  doesn't exist. according to canvas fileupload api guidedoc:

"parent_folder_path: The path of the folder to store the file in. The path separator is the forward slash `/`, never a back slash. The folder will be created if it does not already exist. This parameter only applies to file uploads in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used"

[ordwaye]

On the test instance is there is limit to api call speed?

I am using the api to inactivate the section enrollments of students that have left a course.  I am testing it in our test instance and initially the app would do a dozen or so api calls and the stop getting a response from canvas.  I inserted a sleep of a couple seconds between calls and it to processed a lot more calls before doing the same thing.  I am trying to figure out if this is an issue on my end, some limitation on the test instance or if it is a limitation on all instances.

Thanks

[themidiman]

One thing I have encountered is that the amount of cloud computing resources dedicated to non-production instances of Canvas are significantly less than the production environment. Even when accessing the admin area in the test or beta environment with my web browser I've had the request time out on occasion. Our institutional cloud contract includes a 'sandbox' instance of Canvas that isn't synced with the production environment and seems to be on par with the resources allocated to our production environment. So for testing speed of API calls I test against that after importing any needed course information from the production environment. That way I can just swap out the URL for the production environment when I need.

[ordwaye]

Just to be clear this is running in the test instance.  It is manipulating enrollment records so that is not something I would test in prod.  If others are having timeout issues in test I will run with the idea that it may not be an issue on my end and test accordingly. 

Thanks.

[garth]

I have found that test and beta can sometimes lag a bit, but not to the point of frustration.

The only significant issue I've had with test and beta has been associated with testing SIS imports.

Apparently we are all sharing a workflow queue in these environments, so if someone is testing a long running job at the same time you are, you might have to wait a while.  My specific scenario was uploading a small SIS import file and watching the status sit at 0% for an hour before it started to process.

Honestly I have not experienced any timeout issues when testing API calls.  We run several complex algorithms that make multiple API calls, and timeouts have never been an issue.  One API call that can take a long time to return is related to course analytics, and even that does not timeout for us.

[dgrobani]

I find the test instance to be quite slow, sometimes maddeningly so. The beta instance regularly times out on me.

[jpgorrono]

I am trying to get a email notification sent for an enrollment invitation and the email never gets sent. Sending a message to the same user via the ui widget works fine. Can anyone tell what I am missing? Appreciate your looking.

curl https://server.edu/api/v1/courses/sis_course_id:autoenrollmenttest1/enrollments \

-X POST \

-F 'enrollment[user_id]=sis_user_id:jpg_goog' \

-F 'enrollment[type]=ObserverEnrollment' \

-F 'enrollment[enrollment_state]=invited' \

-F 'enrollment[notify]=true'  \

-H "Authorization: Bearer `cat ~/canvas/tokens/sis@canvas`"

The enrollment get created:

{

    "associated_user_id": null,

    "course_id": 133067,

    "course_integration_id": null,

    "course_section_id": 127851,

    "created_at": "2017-01-11T00:02:23Z",

    "end_at": null,

    "enrollment_state": "creation_pending",

    "html_url": "https://server.edu/courses/133067/users/123989",

    "id": 687239,

    "last_activity_at": null,

    "limit_privileges_to_course_section": false,

    "role": "ObserverEnrollment",

    "role_id": 8,

    "root_account_id": 1,

    "section_integration_id": null,

    "sis_account_id": null,

    "sis_course_id": "autoenrollmenttest1",

    "sis_import_id": null,

    "sis_section_id": null,

    "sis_user_id": "jpg_goog",

    "start_at": null,

    "total_activity_time": 0,

    "type": "ObserverEnrollment",

    "updated_at": "2017-01-11T00:02:23Z",

    "user_id": 123989

}

[themidiman]

If you're getting a HTTP 200 OK response from the API and you see the observer role in the enrollments, I might wonder if something simple like the course being in a published state is all that's missing? If the course is unpublished notifications don't get sent out.

[jpgorrono]

Thanks for the reply and thatv ery reasonable guess. The test course was indeed not published but after deleting the enrollment, publishing the course and retrying the api call again, still no email. I also created a new course (different sis_id), published it, and enrolled same user in it, in case there was any kind of object conflict with the old enrollment... and still no email arrives and nothing in Spam folder