How deep a nest for my REST?

No, this post is not about ornithology or family life. It is about coding, design decision, software engineering, product development and likely, in that order too.

We made a decision to build the Wiztr API layer as RESTful as possible. Ruby on Rails (RoR) is what we are using to do this.

Spec for the API routes quickly started to look like the following:

/businesses/1/coaches/2/classes/3/students

That is 3 levels of nesting for interacting with certain resources.

In defense of the above, it makes it very easy to look at the API pattern and follow along. In the above example, we can understand or guess that we are likely trying to get ALL the students in class 3 of coach 2 in business 1.

It is almost breadcrumb-like.

It however makes it monstrous, as this post shows. Kinda like introducing yourself before every conversation as /planets/{earth}/genus/{homo}/species/{homo sapiens}/names/{john doe}.

You get the idea.

The RoR best practice explicitly recommends the following in this guideline article:

Resources should never be nested more than 1 level deep.

And, we have settled on our API routes along this best practice. So what we now have is as follows:

/businesses/1/coaches
/coaches/2/classes
/classes/3/students

Now, we can REST easy (no pun intended ;=)

PS: While our preference is to REST, we have identified specific needs for which we are developing non-RESTful convenience routes. For example, this route /classes/:id/request_signup should allow a student to initiate a signup request for the class identified by :id.

PPS: I had blogged about this several months back here.


Comments (0)

Leave a comment