Correct ReST URI design

Question

I have the following (hypothetical) scenario:

Application to report on students in classes in schools. I have 3 tables school, class, student. Class has a FK school_id and student has a FK class_id.

I have my Entities all set up and ready to go and I am about to expose them via a Rest interface.

Should my URIs look like this: Schools - list of schools
Schools/{id} - specific school
Schools/{id}/classes - list of classes
Schools/{id}/classes/{id} - specific class
Schools/{id}/classes/{id}/student - list students
Schools/{id}/classes/{id}/student/{id} - specific students

Even though in the case of specific student I will be ignoring the I will be ignoring the school id and the class id as all I care about for my query is the student id.

Should I just have: Schools/student/{id} - for specific students.

Answer 1

There's no problem with exposing a resource from multiple locations (though it's a good idea to specify the canonical url if there are multiple locations*).

Thus it may make sense to provide all the following URIs:

lists:

student
classes/{id}/student
schools/{id}/classes/{id}/student

specific:

student/{id}
classes/{id}/student/{id}
schools/{id}/classes/{id}/student/{id}

In your case the relationship between entities is not an entity itself. If this were the case (eg. if you had the resource class-student with an attribute specifying how long the student had been in the class) then the URIs that include both class and student ids become more important as they provide a good place to expose the attributes of the relationship itself.

*to best provide the canonical url to the client you can send it as the value of the "Content-Location" in the response headers.

Answer 2

Also, it is useful to have a convention for using plural/singular names. Some people like only singular names, some (like Ruby folks) using both and a conversion tool. For example, in Ian's answer student list URL must be students .