Question

I have implemented a Rest API with vectored ids:

http://example.com/api/user/1
http://example.com/api/user/2
http://example.com/api/user/1,3
http://example.com/api/user/1,2,3

Rest dictates that if "user/2" doesn't exist to return a 404.

Disregarding a possible solution that involve query parameters, what are the appropriate responses for the following situations?

user/1,2 - user/1 exists and user/2 exists
Response is a 200 with both elements returned in a set

user/1,3 - user/1 exists and user/3 DOES NOT exist
1? Response is 200 with the user 1 in a set?
2? Response is 404 because user/3 can't be returned?

And since we could possibly be dealing with empty sets with 1? above, does this mean
user/3 - user/3 doesn't exist
1? Response is 200 with an empty set?

Was it helpful?

Solution

Make sure that response format is the same for single ID and several IDs (vectored IDs). It's one of REST principals: GET is a "safe method" (nullipotent) and should produce no side-effects.

For endpoints that support vectored IDs in GET request I usually use response format similar to OpenSearch i.e.

GET user/1,3 where user/1 exists and user/3 does not exist returns 200 with

{
  "startIndex": 0,
  "count": 1,
  "itemsPerPage": 1,
  "entry": [
    { /* user/1 */}
  ]
}

GET user/3 where user/3 does not exist returns 200 with

{
  "startIndex": 0,
  "count": 0,
  "itemsPerPage": 0,
  "entry": []
}
Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top