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.

[kenneth_larsen]

That one I am not sure of. I have used Postman only once. I use PHP and JavaScript for all of the API calls I run so I am not really familiar with what Postman can and can't do.

[kenneth_larsen]

You can only view information using the API that you can view using the User Interface. In other words, you can only pull courses you have a right to view.

[kenneth_larsen]

Try using the list active courses in an account API and use your institutions root account ID.

[tom_lamy]

Hello,

I use Perl and Canvas APIs to do all my SIS work. Here are some examples:

Create a course: /usr/bin/curl -s 'https://$DOMAIN.instructure.com/api/v1/accounts/$account_id/courses' -X POST -H '$AUTH_HEADER' -F 'course[name]=$course_name' -F 'course[course_code]=$course_code' -F 'course[sis_course_id]=$course_id' -F 'course[term_id]=$term_id'

Create the course section: /usr/bin/curl -s 'https://$DOMAIN.instructure.com/api/v1/courses/$canvas_course_id/sections' -X POST -H '$AUTH_HEADER' -F 'course_section[name]=$course_name' -F 'course_section[sis_section_id]=$section_id

Apply a template: /usr/bin/curl -s 'https://$DOMAIN.instructure.com/api/v1/courses/$canvas_course_id/content_migrations' -X POST -H '$AUTH_HEADER' -F 'migration_type=course_copy_importer' -F 'settings[source_course_id]=$template_number'

Enroll user: /usr/bin/curl -s 'https://$DOMAIN.instructure.com/api/v1/courses/$canvas_course_id/enrollments' -X POST -H '$AUTH_HEADER' -F 'enrollment[user_id]=$canvas_user_id' -F 'enrollment[type]=$role' -F 'enrollment[course_section_id]=$course_section_id' -F 'enrollment[enrollment_state]=active'

The enrollment and template calls are dependent on getting the the canvas_course_id and the canvas_section_id respectively. To do that, I stuff the json message returned from each call into a variable called $messages. From here I can located the "id" and store it in a variable. This is the code:

my $char = "id\":";

my $begin = index($messages,$char);

      $begin+=4;

my $end = 10;

my $canvas_course_id = substr($messages,$begin,$end);

   $canvas_course_id =~ s/\D+//g;

I do the same to get the canvas_section _id so I can enroll my users.

[dstraayer]

I'm looking for some sample Java code to interact with the Canvas API.

I teach math and Java at Tacoma Community College.  I'm thinking of learning to use the API as a professional development goal, and also to overcome some limitations in the way the gradebook handles extra credit.  I just learned of the existence of the API at a recent Washington State Canvas conference hosted here at TCC.

I've learned lots of languages and tools, dating back decades.  I've always found the most effective jump-start is to find some working example code, and start tweaking with it.  It looks like it would take months of reading to begin a Java project using the API "from scratch".

Can anyone point me to some simple Java code to access my Canvas courses?  I'd expect to have to edit in things like the OAuth2 token, my college name, a course ID, etc.  It looks like it shouldn't take too much code to do that, but two days of searching haven't yielded me any starting point.

I'd very much appreciate some sample code, or pointers to where else to ask.

Dave Straayer

[ordwaye]

If you are will to work in ruby there is a prebuilt gem , pandarus, that wraps the whole api and is pretty easy to use.

GitHub - instructure/pandarus: A Ruby library for the Canvas API (and code generator for other langu...

[dstraayer]

Thanks, but I'm wedded to Java because I have to teach it.

I've found one library, but the Java is deeply intertwined with Android libraries.  It would take a lot of time to disentangle that, so I'm still hoping that someone, somewhere, had used the Canvas API from Java and can share some example code.

[themidiman]

Sounds like what you would want to do is find a Java REST client library and JSON library. I've not used Java to do this, but it would seem pretty straightforward. Searching around brought me to some promising results:

• Resty (Java REST client library)
• GitHub - stleary/JSON-java: A reference implementation of a JSON package in Java.

[jpgorrono]

 @dstraayer 

I've been using this: https://github.com/kajigga/canvas-contrib/tree/master/SIS_Integration/java/basic_example

The sis import API interaction is in SISImport.java. I forked and copied the classes involved, made some mod's to the config class etc. But for the most part kept it intact.

It's only one API interaction example, but hope that helps

Jon

[mcarruth]

In our previous LMS, we could query the log files to determine the number of times an individual link (URL, External tool, etc.) the a course was selected.

Is there a way to determine the number of time student / teachers click on a individual module item in a course?

[reevesj]

I am trying to automate attaching files to an assignment using the API.  I've successfully added comments to an assignment like this:

curl 'https://auburn.instructure.com/api/v1/courses/NNN/assignments/OOO/submissions/PPP' \

   -X PUT \

   -F 'comment[text_comment]=Good job.' \

   -F 'submission[file_ids][]=72819643' \

   -H "Authorization: Bearer <token>"

However, when I try to upload a file like this:

curl 'https://auburn.instructure.com/api/v1/courses/NNN/assignments/OOO/submissions/PPP' \

   -X PUT \

   -F 'comment[text_comment]=Good job.' \

   -F 'comment[file_ids][]=72819643' \

   -H "Authorization: Bearer <token>"

it says

{"status":"unauthorized","errors":[{"message":"user not authorized to perform that action"}]}

I have carefully gone through the process of uploading the file and checking the file_id.  It is correct.

FYI, if I do the following:

curl 'https://auburn.instructure.com/api/v1/courses/NNN/assignments/OOO/submissions/PPP' \

   -X PUT \

   -F 'comment[text_comment]=Good job.' \

   -F 'submission[file_ids][]=72819643' \

   -H "Authorization: Bearer <token>"

I don't get an error, but it doesn't upload the file as a submission.

Any suggestions would be appreciated!

[MattHanes]

First of all, War Eagle...

Second, I think a file upload is a POST and not a PUT. Uploading Files - Canvas LMS REST API Documentation Could that be why you get that error?

[reevesj]

War Eagle!

It starts with a POST.  But the final step is a PUT that just informs Canvas of the file_id.  However, your comment has given me an idea of something I may have done wrong.  I'll try it out and report back.

Thanks!

[reevesj]

Well, my idea didn't pan out. I thought the problem might be that I didn't upload the file properly. I'm not sure I had uploaded the file to the correct API endpoint. But I made sure I did that. I used:

curl 'https://auburn.instructure.com/api/v1/courses/NNN/assignments/OOO/submissions/PPP/comments/files' \

-F 'name=ABET.pdf' \

-H "Authorization: Bearer "

After that I did as before, and I got the same result. The text comment is uploaded, but the attachment isn't.

[mwhite]

Hi Stan,

You say "I am trying to automate attaching files to an assignment using the API."  But in looking at the routes you are hitting, it looks like you are trying to do something else.

If you want to post a file as a submission for an assignment, then consider the fact that submission objects in canvas are immutable so if you are making a new submission then you will always POST. The only time you would PUT to a submission would be for comments and / or grades.

And if I am still understanding you properly, I am gonna ask an obvious question here. Does that assignment accept file upload submissions?

However, if you are trying to PUT a comment to a submission and include a file then the file must be added using this route first:

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/comments/files

Submission Comments - Canvas LMS REST API Documentation

And then

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

with the param comment[file_ids][]=XXX

Submissions - Canvas LMS REST API Documentation

Note:  comment[file_ids][] -- Attach files to this comment that were previously uploaded using the Submission Comment API's files action

Hope that leads you in a good direction!!!

[reevesj]

Matthew,

I apologize for my poor summary of what I'm doing. It is your latter guess -- adding comments and attached files as comments to a submission.

As far as I can see, I'm doing it precisely as you describe. I'm getting no error message, but the response shows no attached file and neither does the submission comment listing. A text comment is added but no file.

[mwhite]

One more quick question before I trouble shoot more. For the :user_id, please confirm you are using the student's ID and not yours.

We will get this going!!

[reevesj]

Yes, that's right. And just to confirm, I've verified that the text comment is showing up in the student's submission. So I'm at least getting all that right. But the file attachment does not.

Is there anything I can do to troubleshoot or get some sort of informative response when I issue the PUT? It seems to just return the submission info (without the new file but with the comment) but no error.

[reevesj]

Matthew, do you have any more suggestions?

[mwhite]

Stan, Friday got crazy on me.

I am going to run through the process right now. I have done a lot of file uploads, but never a file upload for a submission comment. I will get back to you shortly on what I find.

Few points of clarification:

It looks like you are uploading from your computer, correct? As opposed to a HTTP URL?

Are you using bash scripting to run these API's, or was that just for the community?

All my work with API is through JavaScript and Scala, so I will be pointing Canvas to an https url, this shouldn't matter, but just pointing out any potential differences.

Matthew

[mwhite]

reevesj​

I was able to upload a file as a submission comment. So let's step by step this.

One thing to note off the bat that I did not see in your comments. The first POST for a submission file upload is to a different route than to a course file upload. Please confirm you used:

POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/comments/files

From there you receive a data object back, something like:

"{"id": 9999,

"upload_status":"pending",

"status_url":"https://everspring2.instructure.com/api/v1/files/1234/abcFile567/status"}"

Do a GET on the status_url. Once you receive a data object that looks like

{"upload_status":"ready"

  , "attachment":{

    "id":9999

  , "folder_id":null

  , "display_name":"pic.jpg"

  , "filename":"141234_151__pic.jpg"

  , "content-type":"image/jpeg"

  , "url":"https://everspring2.instructure.com/files/1234/download?download_frd=1\u12326verifier=123"

  , "size":110049

  , "created_at":"2016-04-17T17:59:34Z"

  , "updated_at":"2016-04-17T17:59:35Z"

  , "unlock_at":null

  , "locked":false

  , "hidden":false

  , "lock_at":null

  , "hidden_for_user":false

  , "thumbnail_url":"https://instructure-uploads.s3.amazonaws.com/account123000001/thumbnails/123/14609974_151__pic_thumb..."

  , "modified_at":"2016-04-17T17:59:34Z"

  , "locked_for_user":false

  }

}"

You now know that instructure has successfully place your file on their sever.

Final step is to PUT to a submission at the route:

/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id?comment[file_ids][]=9999

Please let me know if you find success in this! I am more than happy to continue helping.

One note: While I am an admin on our instances of canvas, I did this logged in as one of our test teachers to ensure teachers were in fact authorized to perform this action.

[reevesj]

I have gone through this thing painstakingly and still no joy.

First, it appears that you're uploading via URL. I am uploading a local file. I followed the instructions under "Uploading via POST at https://canvas.instructure.com/doc/api/file.file_uploads.html

I followed all three steps, and everything proceeded according to the instructions with one small difference. Where it says the response should be:

HTTP/1.1 301 Moved Permanently Location: https://<canvas>/api/v1/s3_success/1234?uuid=ABCDE I got:	HTTP/1.1 303 Location: https://<canvas>/api/v1/s3_success/1234?uuid=ABCDE

However, Step 3 worked fine, and I was even able to download the document via the URL provided in the response to #3.

Next, I extracted the ID from the response and did a PUT exactly as you indicated. I'm using curl, and here's my command:

curl -i 'https://auburn.instructure.com/api/v1/courses/AAAAAAA/assignments/BBBBBBBB/submissions/CCCCCCC' \

-X PUT \

-F 'comment[file_ids][]=9999' \

-H "Authorization: Bearer "

A comment appears in the student's submission that says "See attached files." just as though a file was attached. But no file is attached.

As an experiment, I put in a bogus file ID and got the same behavior. No error or anything, but the text comment shows up and nothing else. The most obvious explanation is that I'm somehow putting in the wrong file ID, but there's seemingly no way to mess that up. I'm using the "id" that comes out of Step 3 in Uploading via POST, the one labeled "1234" in the example:|

{|

"id":1234,"url":"...url to download the file...","content-type":"image/jpeg","display_name":"profile_pic.jpg","size":302185}

So, I'm clueless at this point.

[mwhite]

Ok so this is going to be some painfully annoying thing but you are too close at this point to not see this through. Your calls appear to be all correct, this has to be some setting thing.

Authentication is good.

As far as local v url upload, we should be good because we know your file got to their server, as demonstrated by your ability to download from s3 url.

All we are attempting to do now is create a submission comment with a file that we know exists on their server.

Digging deep on these ideas:

1) Are you able to create a submission response with an attachment via the Canvas UI? Just to confirm you can perform this task in general.

2) Are you able to upload a file to the course? Instead of the submission comment url, see if you can just get a file on the course. To confirm you can add files to a course.

3) Go into the settings of the course and check the "File Storage:" setting to make sure you have enough. This one is a long shot, but you never know.

Good luck!!!

[reevesj]

1) Are you able to create a submission response with an attachment via the Canvas UI? Just to confirm you can perform this task in general.

Yes. I assume you mean via the normal web interface, and you're referring to submitting a comment file attachment. I don't think there's a way for me to submit on behalf of a student.

2) Are you able to upload a file to the course? Instead of the submission comment url, see if you can just get a file on the course. To confirm you can add files to a course.

Yes. It created a new folder called "unfiled" and the file was inside there.

3) Go into the settings of the course and check the "File Storage:" setting to make sure you have enough. This one is a long shot, but you never know.

2000MB

[mwhite]

One more thing. You said you are seeing "See attached files"... I bet they are there.

Do a get on that submission with include[]=submission_comments

See if your file shows up there.

[reevesj]

Not there.

And there's no attached file even after a refresh.

BTW, I don't know that it's relevant, but there's already one comment with an attachment (from using the web interface).

I'm working on your three suggestions...

[mwhite]

How big is the file you are uploading?

Another note - I noticed that when I submit a file through the UI, I see the "See attached file" with no file there. And then I refresh the screen and it shows up. Maybe do a hard cache clear refresh??? Reaching on that one too...

[reevesj]

My file is 20K.

[mwhite]

I am going to side by side bash script / js console this today.

I haven't experienced anything like this with their apI before!

[mwhite]

I was able to successfully upload a submission comment via with CURL with an https URL. For some reason when I was trying to do it locally, I was getting some 403's when trying to upload my file to the s3, but you are not experiencing that.

2 things:

1) It is still odd that the submission comment says "see attachment", do a GET request on that submission with the param include[]=submission_comments and see if the JSON file has a url with your file.

2) Attempt to do this process with an https url to a file. Here is an easy one "https://s3.amazonaws.com/uifaces/faces/twitter/k/128.jpg "

Persistence and hard headed-ness will lead us to victory!

[reevesj]

OK, finally had time to look into this.

1) It is still odd that the submission comment says "see attachment", do a GET request on that submission with the param include[]=submission_comments and see if the JSON file has a url with your file.

I had actually already done this at your request earlier. I did it again. There is no URL and no attachment associated with the comment.

2) Attempt to do this process with an https url to a file. Here is an easy one "https://s3.amazonaws.com/uifaces/faces/twitter/k/128.jpg "

I followed the instructions for a URL-based upload. Got the ID from it. Used curl as follows to PUT the file_id:

curl -i 'https://auburn.instructure.com/api/v1/courses/NNNNNN/assignments/OOOOOOO/submissions/PPPPPPP' \

-X PUT \

-F 'comment[file_ids][]=1234' \

-H "Authorization: Bearer "

It returned the submission, showing a new "See attached message" but with no attached file URL listed. Argh!

[reevesj]

Did you throw up your hands in hopeless resignation? I can't see where to go next.

[mwhite]

Hi Stan,

So sorry for the delay. We had a great but very large launch last week that was all consuming.

Here is where I think we are at. You are doing everything right, so this end point should be working. Are you guys self hosting your instance of Canvas? Maybe this endpoint doesn't exist with your instance??? shot in the dark.

I see that you are a CompSci teacher, maybe this is a great assignment for you students. For this weeks assignment, create a blank submission. Then using the Canvas API, post a submission comment with a txt file containing the scripts you used to post this submission comment. HA!

Matthew

[alex_weaver]

Hi All,

Does anyone have any experience with creating and updating using the API without the use of a file.

I'm trying to write a c# program to update all courses with an sis_course_id field using a JSON string.

I can send data using the API and get a successful return code but the record will not update.

My code is below,  any help would be greatly appreciated.

//Declare variables
string canvasUrl = "https://XXXXXXXX.instructure.com/";
string authToken = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
//Create HTTPClient link to Canvas
Connection connection = new Connection();
HttpClient client = connection.CreateHttpClient(canvasUrl, authToken);
//Update course with id 200
string jsonString = @"{""sis_course_id"": ""123456""}";
HttpContent httpContent = new StringContent(jsonString, Encoding.UTF8, "application/json");
HttpResponseMessage response = await client.PutAsync("api/v1/courses/200", httpContent);

[MattHanes]

Greetings  @alex_weaver ​,

I believe the error is in your JSON string. I think you are supposed to specify that you are modifying the course object. Like this:

{

  "course": {

    "sis_course_id": "123456"

  }

}

At least, that's how I do it in Python.

[alex_weaver]

Hi  @MattHanes ​,

Thank you so so so so so SO much. You have saved me no end of pain and countless hours of work in one quick reply. It worked first time without issue and I can now post data via the API.

You have made my day and week!

Kind Regards

Alex!

[MattHanes]

Glad I could help! I remember struggling with that same concept when I started fiddling with API. In case you don't know, canvas has a live API that you can test with. The URL for the live API is https://<yourinstitution>.instructure.com/doc/api/live

You can even do https://<yourinstitution>.test.instructure.com/doc/api/live so you don't accidentally mess with anything in production. It kind of lets you play around and see what different calls do without having to write the code for them.

[reevesj]

Matt,

This sounds interesting. When I tried a command to

https://auburn.test.instructure.com/doc/api/live/courses/NNNNNN/assignments/OOOOOOO/submissions/PPPP...

I got an HTML message "The requested method PUT is not allowed for the URL /doc/api/live.html/courses/NNNNNN/assignments/OOOOOOO/submissions/PPPPPPP."

Have I misunderstood how to use it?

[alex_weaver]

reevesj​ Can you post the command you are trying to run? I assume you are using this call?

/v1/courses/{course_id}/assignments/{assignment_id}/submissions/{user_id}         

• Grade or comment on a submission

[reevesj]

Yes.

Here's the command expressed with curl:

curl -i 'https://auburn.test.instructure.com/doc/api/live/courses/NNNNNN/assignments/OOOOOOO/submissions/PPPPPPP' \

-X PUT \

-F 'comment[file_ids][]=9999' \

-H "Authorization: Bearer "

and got the same response.