How to name RESTful endpoint that's described using two identifiers?

Question

When resource has a unique identifier it is retrieved:

/building/{building_id}

But what if "event" resource is described using building_id and floor_id parameters. How to name RESTful endpoint that is meant to retrieve present events?

To be precise, "event" resource has a unique identifier (id). Combination of building_id, floor_id ought to return present event in a particular location.

Answer 1

But what if "event" resource is described using building_id and floor_id parameters.

Is it? I recommend this:

If

GET /events/{id}

returns one event and

GET /events

returns all events, then

GET /events?building_id={building_id}&floor_id={floor_id}

returns the list of (possibly only one) event(s) at the combination of building_id and floor_id.

This looks like the often used filter-or-search-a-collection-resource-pattern.

Answer 2

Apart from the solution by Lutz, in case if you dont want them to be query parameters.
Assuming, from the name as it looks, floor_id is part of building_id , so if the event resource is defined as combination of both , it can be like

/event/{event_id}/building/{building_id}/floor/{floor_Id}

Answer 3

I'd start by trying to think what resource owns what. Obviously, buildings own floors (knock the building down, the floor is destroyed!) so that's a relationship that maps nicely to a sub-resource, but do events own buildings or do buildings/floors own events? No? Then we relate these by links. (A floor might have a current event concept as something it owns, but that's really a link to an event, not an event per se.)

/building/{building_id}
/building/{building_id}/floor/{floor_id}
/building/{building_id}/floor/{floor_id}/current-event --redirect--> some event
/event/{event_id}

The event probably should have hyperlinks to the building and floor which it involves. Going the other way, if there's no current event for a floor, fetching the …/current-event will result in a 404, and if there is an event, a 303 redirect will say which it is. (You might also want to make the record for the floor itself contain a true link to the event, as well as a convenience lookup sub-resource.)

A good RESTful application looks an awful lot like a densely linked website. Use the power of links and redirects!