I'm designing a read-only REST API where users are asking for a performant mechanism to read multiple objects at once. Here are some options I came up with.
- NO read multiple endpoint. Just provide the read all and read one endpoints and leave it up the client to fetch each object incrementally:
GET /api/orders/
GET /api/orders/1/
This isn't going to be performant for clients that need to get hundreds of objects at once, which is a fairly common use case for this system.
- GET with comma-separated list of multiple objects:
GET /api/orders/1,2,3/
We may hit URL length limits (which is certainly possible for this use case) and this forces us to use the singular form of the entity, e.g. GET /api/order/1/ to fetch a single instance which is unintuitive for users.
- Add filtering to GET all endpoint:
GET /api/orders/?ids=1,2,3
We don't need to create an entirely new endpoint but we still may hit URL length limits.
- GET with body:
GET /api/orders/ ids=<ID's>
This appears to be a very bad practice. Not intuitive and you run into caching issues.
- POST as GET:
POST /api/orders/ ids=[1, 2, 3, ..., 1000]
POST is meant for creating objects only and we may run into caching issues.
Moreover, I'm not sure the best way for structuring the "GET multiple" response? I want to paginate the result set and indicate which order ids were not found. This is what I currently have:
{
"count": 997,
"next": "https://api.example.org/accounts/?page=5",
"previous": "https://api.example.org/accounts/?page=3",
"results": [
…
],
"missing": [998, 999, 1000]
}
So my question is, does anyone know the best way to design this? I'm leaning towards the POST as GET implementation but it certainly isn't perfect.
