How to specify many ids and their variable name in a REST API request?

Question

What is the most common and wise way to specify many entities' ids in an API request?

For a singular entity request I have:

GET /v1/entities/{entity_id}

My suggestions for requesting many entities:

GET /v1/entities?entity_ids={entity_id1},{entity_id2}

With the same variable name entity_id:

GET /v1/entities?entity_id={entity_id1},{entity_id2}

More looks like for singular endpoint:

GET /v1/entities/{entity_id1},{entity_id2}

Or is there any other way to design for such endpoints?

Answer 1

I'm afraid the standard thing to do is not to search multiple ids like this using REST. If you're loading several specific entities by id, then you should ask yourself why you're doing so. Perhaps these entities are customer orders belonging to a specific customer and you're loading the details of each order. In that case, you should have a URL more like /customer/{id}/orders which returns all orders belonging to a customer with id {id} rather than knowing the ids beforehand and loading them each individually.

Otherwise if the user is attempting to load several entities from a list to view its details, simplify the display to show one entity detail at a time, and you load each one as the user moves forwards or backwards. In other words, you shouldn't be in a situation where you'd specifically need multiple entities loaded by their ids with no obvious link between them that you'd need a way to call the REST service with each individual id listed.

Answer 2

All these approaches share the same issue: they bloat the request string when many IDs are queried. When there are cases when many IDs are requested you can likely get into the situation where a gateway server rejects the request because the query string exceeds some limit (usually around ~2000 chars).

With that in minde none of these options is any wiser than the other.

I have seen the last approach in several APIs while i have not seen any of the others. I recommend you go with

/entities/id1,id2

---

A side note: dont do API versioning via the URL if you want to be RESTful. Entity#5 ist still Entity#5, no matter what the API version is that you access it through. The consensus is to use header for the versioning:

X-API-Version: 1