cancel
Showing results for 
Search instead for 
Did you mean: 
Highlighted
Community Member

REST API Required Request Parameters

Jump to solution

I've recently begun to work with the Canvas REST API and wanted to know if there is a list somewhere that tells you which parameters are required & which are optional for REST requests?  For instance, according to the API, the request to create a Course uses 28 parameters.  However, it doesn't look like all of the parameters are strictly required.  In fact, the description for the very first parameter listed - course[name] - states that it can be omitted.

For that matter, is there a comprehensive list that describes ALL of the parameters available for the underlying objects?  That is, if you look at the REST request to create a new Course, one of the parameters listed is  course[allow_student_wiki_edits].  This parameter is not listed under "A Course object looks like:".  Conversely, the field course[allow_student_assignment_edits] is listed under "A Course object looks like:".  However, there is no Course request provided that uses this parameter.

Thank you.

1 Solution

Accepted Solutions
Highlighted
Navigator

kurt.faulknerloser@rccd.edu​,

The API documentation that you're looking at indicates when a parameter is required. Perhaps the course creation endpoint you looked at doesn't have any required parameters, but if you look the course deletion or course update, they do.

212624_pastedImage_0.png

I won't say that the documentation is perfect, and there are discrepancies between the documentation, the examples, and the actual code. There's been a couple of places where someone has pointed out a parameter that exists in the example object but not in the request parameters, but (at least in those cases) when you try to use it, it works.

Another thing I do is to click on the link at the top right of the endpoint to get to the source code for that controller. I don't speak Ruby fluently, but I can sometimes figure out what's going on from that.

212625_pastedImage_1.png

The part after the hash # is the particular code that relates to that endpoint. In this example, it's create.

You can search for def create to find its definition.

Another thing you can do is use the Live API. It's at your Canvas instance with /doc/api/live appended at the end. It's really useful for seeing everything in one place and testing it out. You'll need to put your access token in at the top before you can do things with it, though.

Finally, one general observation. For GET, PUT, and DELETE requests, required parameters are usually specified as part of the path, not as a response parameter. These are the things like :account_id and :course_id that you see. For POST requests, there may be additional required elements that are specified in the documentation.

View solution in original post

15 Replies
Highlighted
Community Coach
Community Coach

Due to the technical nature of this question I'm going to share it with the Canvas Developers group in the Community. They are the ones that work with this side of Canvas and should hopefully be able to help! In addition, you might consider joining the Developers group and checking out some of their other resources/information!

Highlighted

Thanks for the fast reply Kona!  I followed your advice & just joined the Canvas Developers group.

Highlighted
Navigator

kurt.faulknerloser@rccd.edu​,

The API documentation that you're looking at indicates when a parameter is required. Perhaps the course creation endpoint you looked at doesn't have any required parameters, but if you look the course deletion or course update, they do.

212624_pastedImage_0.png

I won't say that the documentation is perfect, and there are discrepancies between the documentation, the examples, and the actual code. There's been a couple of places where someone has pointed out a parameter that exists in the example object but not in the request parameters, but (at least in those cases) when you try to use it, it works.

Another thing I do is to click on the link at the top right of the endpoint to get to the source code for that controller. I don't speak Ruby fluently, but I can sometimes figure out what's going on from that.

212625_pastedImage_1.png

The part after the hash # is the particular code that relates to that endpoint. In this example, it's create.

You can search for def create to find its definition.

Another thing you can do is use the Live API. It's at your Canvas instance with /doc/api/live appended at the end. It's really useful for seeing everything in one place and testing it out. You'll need to put your access token in at the top before you can do things with it, though.

Finally, one general observation. For GET, PUT, and DELETE requests, required parameters are usually specified as part of the path, not as a response parameter. These are the things like :account_id and :course_id that you see. For POST requests, there may be additional required elements that are specified in the documentation.

View solution in original post

Highlighted

Thank you so much for the help James.  I really appreciate the hint about the link on the right & the /doc/api/live URL.  I'm sure that your advice will come in very helpful as I move forward.

Highlighted

Hi James

Greeting from Hobart Smiley Happy

I'm looking at the documentation of a random api call:

Update an appointment group [Canvas LMS REST API Documentation ]

I'm not sure what the documentation is trying to say.

Do you know what the empty list on the end of the parameter means?

appointment_group[context_codes][]  Required    string

Further down the list of request parameters you get this one with an 'X' in it, what does that mean ?

appointment_group[new_appointments][X][]        string

Thanks

Julian

Highlighted

Sorry to answer my own question Smiley Happy

The answer is here: Canvas Live API 

the [] means an array of string. The api docs just say 'string', technically incorrect!

Highlighted

julian.ebeli@education.tas.gov.au,

People answering their own questions is great!

The documentation is correct, though. The value that you're using for that parameter is a string (the right hand side of the equal sign is a string). The [] in the parameter name itself is what makes it an array. If you're supplying the parameters as part of the query string, then you need to include that [] and repeat the entire thing multiple times if there is more than one value in the array. If you're JSON encoding it, then the values inside the array are strings.

The description even says it's an array. The context codes themselves are strings.

Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.

Highlighted

Hi James

Does a call like this work for you?

https://your.instructure.com/api/v1/courses/[a_course_id]/users?user_id=[a_user_id]

For me it gives the whole user list for the course, rather than a single result.

Thanks

Highlighted

To get a single user you can use:

   .../api/v1/courses/[a_course_id]/users/[a_user_id]