Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Here's one way to tackle it, if behind your REST API is an SQL database:

  /schema/table/key
So:

  //www.example.com/calendar/events/123

To address many records, like all that belong to Bob, use the query string instead of purely the path:

  //www.example.com/calendar/events/?user=bob


This is in my experience the `standard` design; it does give you a lot of freedom to change what filters you allow, and to stack them. Nobody's going to get fired for this design, and there's a lot of prior art around it to draw examples from. It also has the benefit of keeping the API surface small and clean.

But it makes it a bit weird to do HATEOAS; you _could_ do `GET Bob => {events: "calendar/events/?user=bob"}` -- but then you're hyperlinking to a search and not a resource.

It also tells less of a narrative in the structure; `user=bob` is just another filter that you can use to apply to the events set. But we get a chance to describe the shape of the data a bit more if we choose to declare an intermediate resource (/users/) and attach some links to it (=>/users/bob/events).

Now, if there are ten ways that you need to slice your `events` set, and ?user=bob is but one of them, then scoping a sub-resource /users/events/ isn't that useful/descriptive.

As an aside, I think this is where HATEOAS is nice; it makes it very easy to navigate an API as a developer, see what actions are possible at every node, and hopefully learn the intent of the author of the API without having to chew through a set of API documentation. Django Rest Framework's API browser is a great example here.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: