cancel
Showing results for 
Search instead for 
Did you mean: 

Developer Tools #2 - Update a course nickname with the API

robotcars
Navigator
6 6 3,971

Developer Tools for the Canvas User > Tutorial #2

Before getting started with APIs, read through paragraphs 1-5 of the linked thread by  @stuart_ryan 

Canvas APIs: Getting started, the practical ins and outs, gotchas, tips, and tricks

Stuart confirmed there is a working beta environment on the Canvas Free For Teachers accounts at https://canvas.beta.instructure.com


To save on lengthy screenshots, I've combined some panels, please let me know if this causes confusion.

  1. Now that you have the console open, click on the Network tab, and the ⃠ Clear button on the left
    This will clear all the requests that happened during page load
    Drag out some space with the border between the ViewPort (on the left) and the Developer Tools
  2. Now click on the edit button at the top right of any Course Card, change the nickname and the color, click Apply
    You should see two new requests with the course number
  3. Click on the request prefixed with course_ and then the Network Headers tab
    Take a quick peak at the following:
    Request URL - this is the URL (or endpoint) of the request we want to send to the API to change the color, it contains your user and course id's
    MethodPUT - HTTP, and all the Request Methods - HTTP | MDN 
    Status Code200 OK, and all the Response Status Codes - HTTP | MDN 
    Content Typehttps://www.google.com/search?q=JSON
  4. Now click on the Network Preview tab
    This is JSON, I hope you clicked that last link.
    I'll walk you through with Colors first, it's a simple place to start.
    // this is a simple JSON object, with the hex value of the color you chose
    // you'll usually see JSON like you see in the console, with all the white space removed
    {hexcode: "#F0592B"}

    // but it's often useful to nest it with tabs while you're working and learning
    {
         hexcode: "#F0592B" // this is the data that was sent to Canvas to save the color
    }‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

    // it has one (1) value, simple right?‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

    Canvas Developer Tools _ Change Color

  5. That's 5 pieces of information we need to change the color with the API
    URL - API endpoint/api/v1/users/:id/colors/:asset_string
    MethodPUT - replaces all current representations of the target resource with the request payload.
    ID - your user idself - use self when you can't remember your user_id [1]
    Asset Stringcourse_# - get the course number from the course URL
    Parameters{hexcode: "#F0592B"} // the payload you will PUT to the URL
  6. Let's keep it simple and use jQuery to make this API request
    Type or copy the 10 lines below into the Console tab, and edit the course number in the URL
    After you get this snippet into the console, hit Enter
    var payload = { hexcode: '#FDC010' } // yellow

    // http://api.jquery.com/jquery.ajax/
    $.ajax({
        url  : '/api/v1/users/self/colors/course_1214595',
         type: 'PUT',
         data: payload
    })

    // #8BC34A - a green hex code ‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

    {readyState: 1, setRequestHeader: ƒ, getAllResponseHeaders: ƒ, getResponseHeader: ƒ, overrideMimeType: ƒ, …}

  7. You should immediately see a response that looks something like the one above, we'll cover it in tutorial #3, click on the Network tab
    Review the Network Headers and the most recent request for course_#
    Hopefully you'll see Status Code of 200 OK
    If not, compare your code to the snippet above // comments can be ignored, or take a peak at tutorial 3
  8. Click on the Network Preview tab
    You should see a JSON object with the hexcode you sent with the request in the Console tab
  9. Refresh the page
    Unlike tutorial 1, this time you sent the data to the Canvas API where it was saved. When you refreshed the page, you got another copy of the Dashboard with the new color.
  10. Try It Again!
    Go back to the Console tab. To re-execute the last command/code you ran in the console, press the up arrow on your keyboard
    Copy the green hex code from the snippet, and replace the payload value, press Enter
    Pick a different Hex Code with W3 - HTML Color Picker

Congratulations!

You've just used javascript, jquery, ajax, and the Canvas api‌ to Update custom color - Users - Canvas LMS REST API Documentation 

Review the documentation anytime you want to interact with Canvas programmatically. The documentation is a great starting point to any project, then planning how you will use it in your script or program.

:smileycool: Escalating

  1. Let's continue to the Course Nickname.
    Click on the Network request without the course_ prefix, in the screenshot below it's 1214595
    Review the Headers and the Preview tabs as you did above
    Canvas Developer Tools _ Set Course Nickname
  2. Some more JSON, this time with a few more parameters, let's take a look
    // you see a string like this
    {"course_id":1214595,"name":"W○RKR∞M⸚CARROLL","nickname":"My W○RKR∞M ⸚"}‍‍

    // we can indent and format, making it easier to read
    {
         "course_id":1214595,          // the id of the course we want to rename
         "name":"W○RKR∞M⸚CARROLL",     // the current nickname of the course
         "nickname":"My W○RKR∞M ⸚"     // what we are changing the nickname to
    }‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍
  3. Three values were returned in response to setting the Course Nickname using the Dashboard Card. However, we only need to send 1 value to change the nickname.
    Take a look at Set course nickname - Users - Canvas LMS REST API Documentation
    Note the Endpoint and the Method, it looks like this

     PUT /api/v1/users/self/course_nicknames/:course_id

  4. Let's update the snippet of code we used in the first section of Tutorial #2

    We need to update the payload with the nickname, and change the URL

    // update the payload with the values we need to set
    // indent them to be easier to read
    var payload = {
         "nickname":"My W○RKR∞M ⸚ Test"     // what we are changing the nickname to
    }‍‍‍‍‍‍‍‍‍

    // http://api.jquery.com/jquery.ajax/
    $.ajax({
         url : '/api/v1/users/self/course_nicknames/1214595',
         type: 'PUT',
         data: payload
    })‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍
  5. Copy and paste your code into the Console tab (unless you edited it there) and press Enter
  6. You should immediately see a response that looks something like the one above, we'll cover it in tutorial #3, click on the Network tab
    Review the Network Headers and the most recent request for course_#, hopefully you'll see Status Code of 200 OK
    If not, compare your code to the snippet above // comments can be ignored, or take a peak at tutorial 3
  7. Click on the Network Preview tab
    You should see a JSON object with the hexcode you sent with the request in the Console tab
  8. Refresh the page
    You should see your course change names
  9. Try It Again!
    Edit the snippet, change the nickname and press Enter

[1] Profile - Users - Canvas LMS REST API Documentation

      or in the browser console, try ENV.current_user_id

:smileydevil: Rapid Escalation

Check out Developer Tools #3 - Update the DOM with an AJAX Response  and we'll update the Dashboard without Refreshing the page

6 Comments
nschutz
Adventurer

Hi Robert,

Thanks for this helpful blog. So glad I found it. I ran your sample code and it changed the nickname of a course of mine successfully. What I really want to do though is something similar but a PUT request to update an assignment, much like editing an assignment, change something, then click save. I get a 400 response code everytime when I run the code below from the console.

var payload = {
"points_possible":"17" 
}


$.ajax({
url : '/api/v1/courses/xxxx/assignments/xxxxxx',
type: 'PUT',
data: payload
})

The responseText I get says 

 responseText: "{"errors":[{"message":"assignment is missing"}]}"

The URL is correct, matching what's on the network tab and all numbers in the URL are triple checked. I'd truly appreciate any insights you may have. 

James
Navigator II

The payload is wrong. It's not 'points_possible', but 'assignment[points_possible]' that needs changed.

Try this instead;

var payload = {
  "assignments": {
    "points_possible": "17"
  }
}‍‍‍‍‍;
nschutz
Adventurer

Alright, it appears that the payload is formatted incorrectly. It should be as follows:

var payload = {
"assignment":{"id":"318776","points_possible":"17"} 
}‍‍‍

I can pretty much update all the assignment attributes this way, except for the one I really want to update. My payload looks like this and response code is 200, but the field is not updated. 

var payload = {
"assignment":{
"id":"318763",
"configuration_tool_type":"Lti::MessageHandler",
"similarityDetectionTool":"Lti::MessageHandler_39",
"report_visibility":"immediate"}
}‍‍‍‍‍‍‍‍‍‍

All of the key/value pairs are found from the  Request Payload in the network tab when I edit a certain field in an assignment from the browser. These are not values modifiable via API though according to Canvas REST API Assignment, which is why I needed to update them from the client side. Any idea how to update then? In case you are curious what they represent, they represent a plagiarism LTI tool setting in the assignment. 

321773_pastedImage_5.png

James
Navigator II

That seems weird -- the id field isn't part of the assignment object, it's part of the URL. But if it works for you with it but doesn't without it, then I'm not going to argue that point. I'm glad you got it working.

I don't have access to a plagarism LTI tool to verify, so I can only make guesses.

configuration_tool_type only appears in the source code three times. Only one of those lists Lti::MessageHandler. The code that follows immediately is to find the tool_id. The tool_id is found from the similarityDetectionTool. That's the 39 that you have in there. The report_visibility gets saved as originality_report_visibility.  In other words, no clue there as to why it's not working.

Is the assignment that you're updating already an external tool? If not, then there's probably more that needs changed.

Check the URL of the request going to when you update it within the web client? This is not the one you're showing, but I'm talking about under the Headers for the Network request.

321818_pastedImage_4.png

If it has /api in there, then we're in luck and we can get it work outside the web client. If it doesn't have /api in the URL, then it may be because the API doesn't support it.

If the /api is there, then we just need to mimic that call, find out what fields are required and which are truly updates.

Finally, just because the documentation doesn't list something doesn't mean it doesn't work, it just means you have to work harder for it (thus the reverse engineering the requests with the developer tools).

nschutz
Adventurer

James, 

Thanks for the reply. To answer your questions first:

  • I removed the id. (no need to update it anyway)
  • The assignment itself is not an external tool.
  • Yes, the /api is in the Request URL. 

However, here is more that I found out:

  1. The 3 fields that I need to update configuration_tool_type, similarityDetectionTool and report_visibility, they show up in the Request Payload in Headers of the Network request when I update the assignment from the web client. But they are not there when I go to Postman to look the assignment object just updated. In other words, these 3 fields do not "live" in the assignment obj. 
  2. Also noticed, from the same Request Payload in Headers, this field is also in the payload in the assignment object. I guess this is the JWT. Again secure_params does not "live" in the assignment object, which makes sense. I assume when I mimic the call, I need to pass in the JWT in the payload as well? 

321774_pastedImage_1.png

The big question is, how or where to get a JWT? I tried to use the same secure_params in the console like this. I get a rc of 200 but nothing updated. 

var payload = {
"assignment":{"configuration_tool_type":"Lti::MessageHandler",
"similarityDetectionTool":"Lti::MessageHandler_39",
"report_visibility":"immediate",
"secure_params": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsdGlfYXNzaWdubWVudF9pZCI6IjExMWNiNDIxLTJkNTUtNDcxZC04MWQ2LTcyMWQwYzJjZGE2NyJ9.gCj6vzyFgT4h3K_mRRuAGSiNfbeXumrq_I2Zf2im6bM"
}
}
$.ajax({
url : '/api/v1/courses/7483/assignments/318763',
type: 'PUT',
data: payload
})
James
Navigator II

I looked at JWTs at the 2018 InstructureCon with some Canvas engineers and ended up going a completely different route. However, the documentation for them mentions similarity reports, so it may work in this case. I'm not going to be able to help with this one, I don't have any way to test. Here's the API documentation, though: ### JWT Access Tokens for LTI2 Tools. The secure_params is decoded from the JWT, at least for a create. You may also find help by searching the Community for JWT, but it seems to be one of those things that you know how to use if you use them and there's little out for there you if you don't. That is, I found a lot of messages about JWT, but I didn't know how helpful they were for what you're trying to do.