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.

As described in https://cloud.google.com/apis/design/design_patterns#get_uni...:

  //calendar.googleapis.com/users/-/events/123

Hadn't spotted that, it's an interesting syntax and I quite like it.

But it doesn't cover the case I'm referring to; in their example you MUST return the fully-qualified URL:

> shelves/shelf713/books/book8141, not shelves/-/books/book8141

This precludes there being multiple shelves with the same book (sensible in their example, since a book has only one shelf, but not in the example above).

While sometimes this does get tricky with resources that are clearly owned or associated with multiple things, often times a resource only has one real owner and it is unambiguous. It does make moving things a bit weird though, as moving a book between two shelves makes it have a different fully qualified name.

Agree; put another way, sometimes you really do need a M2M relationship.

I prefer the bare minimum approach. That is, if you NEED the user resource to access the event (eg the primary key is like [user ID, event ID]) then nest it in the url. Otherwise if an object has its own ID and could otherwise be accessed independently why not just do so?

The root of this question is: how do you handle M2M relationships in your API?