REST API Design – Boolean Endpoint Implementation

Your solution is OK, save for a few things:

1. Versioning REST APIs at the resource level is generally not a good practice, although this not necessarily a consensus view. See here for some comments and links to further discussion.

2. To your second question, you could probably argue either way as to whether /keys/{id}/ or /values/{id}/ is correct, but my instinct would be to either use keys since it's the "parent" of the tuple, or I'd use an entirely different name such as /data/ or /elements/, or whatever it is these things actually represent.

3. I would probably have different GET methods for the whole key-value dictionary, e.g. /keys/{id}/, and a separate resource for those for a particular user, e.g. /users/{id}/keys/{keyId}.

Finally, it's not great (although possible) to use query strings with POST/PUT/DELETE methods. It is a query string, after all. Instead, you could use POST /data/, and put the key-value pair as JSON data in the request body. See this question as well.

You're right, the behavior is indeed strange. A null and an empty array are, semantically, two different things.

• An empty array indicates exactly that: the array exists but contains no elements right now, given the query parameters.

• An HTTP 404 indicates, on the other hand, that there is no array; for some reason, it makes no sense to have an array there.

Imagine a Flickr-type application with users, photos and comments. Imagine that only paid users can upload photos, but all users can comment. If the user 123 doesn't have a paid subscription and haven't posted any comments yet:

• The query /user/123/comments would give an empty array, but:

• The query /user/123/photos may result in HTTP 404 to indicate that the user is not expected to have any photos.

  Another possibility is to return an empty array, which is semantically correct. You'll lose the “this user doesn't have to have any photos” aspect, but it might not matter too much: if the client needs to know whether user 123 can have photos, the query similar to /account/123/status could be used to return values such as paid or free.