RESTFful/Resource Oriented Design

Question

Suppose I have a three level hierarchy consisting of school, students, and classes.

If I expose student as a resource, my question is whether I should always return the parent "school" and the children "classes" along with that student, or whether there should be parm that the user includes to indicate such. Perhaps something like &deep=True?

Or on the other hand, if a user gets a student, and he wants the school, he has to do a GET on the school resource, and likewise if he wants all the classes that a student is taking, he has to do a GET on the classes resource?

I'm trying to keep the design somewhat open for the unknown future user, rather than coding just for what our current requirements demand.

Thanks,

Neal Walters

Answer 1

I suppose that adding query parameters to optimize delivery is reasonable. I might make it even more generic and use include=<relation>. This can be extended for all types. Note that you can use multiple includes: .../student/<id>?include=school&include=student will assign the list [school, student] to the parameter include. This will also allow a general pattern that may be possibly useful for the other resources as well.

Answer 2

I think you should avoid thinking of classes as a sub-resource or attribute of a student. An academic class is more than just a time slot on a student's schedule; it has an instructor, a syllabus, etc., all of which may need to be encoded at some point.

As I see it, the following relations hold:

• schools have zero or more students
• schools have zero or more classes
• students have zero or more classes
• classes have zero or more students

(You could also trivially extend these with teachers/instructors, if your requirements included such information.)

In addition, each of the above resource types will have any number of attributes beyond the simple links between them.

Given that, I would think you'd want a URL structure something like the following:

• http://example.com/lms/schools => list of schools
• http://example.com/lms/schools/{school} => info about one school
• http://example.com/lms/schools/{school}/students => list of students
• http://example.com/lms/schools/{school}/students/{student} => info on one student
• http://example.com/lms/schools/{school}/students/{student}/courses => list of courses (as links, not full resources) student is enrolled in
• http://example.com/lms/schools/{school}/courses => list of courses
• http://example.com/lms/schools/{school}/courses/{course} => info on one course
• http://example.com/lms/schools/{school}/courses/{course}/students => list of students (as links, not full resources) enrolled in course

Answer 3

If you think about Resource design more in the way you think about UI design then the problem becomes easier. There is no reason why you cannot return a subset of school information within the representation of the Student resource and also return a link to a complete representation of School resource in case the user wishes to see more.

I find it useful to think of a REST interface more like a user interface for machines instead of a data access layer. With this mindset it is not a problem to duplicate information in different resource representations.

I know there are lots of people trying to treat REST like a DAL but they are the same people that get upset when they find out that you can't do transactions via a RESTful interface.

Put another way, design your API as you would design a website (but without any of the pretty stuff) and then build a client that can crawl the site for the information it needs.