Should we abbreviate REST-API endpoints?

Question

I'm wondering what I should do about this REST Api Endpoint: /api/events/<event_id>/instances/<instance_id>/positions

Basically there are events which can have instances and those instances can have positions. I don't want to avoid the /events/ since there could be instances of other things later.

But I don't need the event_id in this case, since all instances are unique among all events.

Is it a bad idea to abbreviate this endpoint to /api/events/instances/<instance_id>/positions ?

Answer 1

You can design the url structure exactly the way you want to. There's no rules, you literally don't need any component of this.

URLs are for humans, so the best thing you can do is make your url structure meaningful for them.

Now with the opinionated part:

It's pretty common for urls to take on a structure /foo/123/bar/456 . This clearly communicates to the user 'bar 456 belongs to foo 123'. Even if there's only 1 'bar' with id 456, the structure here suggests a relationship between these two parts of the url.

But if you don't want the 'foo id' in the url, I'd be more inclined to use a structure like /foo-bar/456 than /foo/bar/456 . So if you have a good reason to leave the 'event id' out, because maybe it's meaningless, I would probably use a structure like /event-instance/<instance_id> instead of /event/instance/<instance_id> .

This is entirely subjective though.

The advantage for having a deeper structure like /api/events/<event_id>/instances/<instance_id>/ is that it suggests to me as a developer that:

1. This instance belongs to a specific event, and it will always belong to that event.
2. I can probably POST to /api/events/<event_id>/instances to create a new instance to a specific event.
3. I can probably GET /api/events/<event_id>/instances to get a list of all instances to the event.

This is not always true, but users that have integrated with a bunch of different APIs will likely expect those things to be true.