REST API – How to Specify Multiple IDs and Variable Names in Requests

apiapi-designrest

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?

Best Answer

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.

Related Topic