REST API Design: Include functionality to see if resource(s) exist in DB or let fetch API error handling handle it?

Question

When designing a REST API, is it common practice to include endpoints that allow you to see if potential resources exists in the database or not (before you eventually fetch them)?

For instance, if I want to request product data using a fetch, should I check to see if the potential resource even exists in the database before fetching it, or should I just let the fetch API catch the error that a non-existent resource would produce?

Is it even common to create endpoints that can be used to tell you if a resource exists in the database or not, or should this all be done through error handling on the proposed fetch itself?

Answer 1

If you want to check for the existence of a resource but not retrieve it, you should be using HEAD.

This method can be used for obtaining metadata about the selected representation without transferring the representation data and is often used for testing hypertext links for validity, accessibility, and recent modification.

There may be a good reason to make a separate endpoint (such as a client not having access to that verb and your not wanting to add verb tunneling support), but in the vast majority of cases a separate endpoint is unwarranted.

It is common and not unreasonable for an API to expect clients to correctly handle a 404 error if the resource they're looking for does not exist. Most clients would prefer to save a roundtrip and handle the 404 rather than making a HEAD call first. If your clients want/need support for an existence check, you should add support for HEAD to your API and point clients to that verb.

Answer 2

As a consumer of your service would I actually use these "exists" type calls? bearing in mind that

1. I would still need to handle the case where the API said the object exists but the actual data retrieval call doesn't find it (because someone else deleted it at just the wrong moment). So I would need to have two different areas of logic to handle the missing data. Seems like more to maintain.

2. I can ignore the "exists" API and I could still just call the data retrieval API and let it fail instead. This may be more efficient for me if the data usually exists-- it'll reduce my number of round trips by up to 50%.

3. Both API calls would probably consume bandwidth at the database tier, so by increasing the calls you are decreasing performance.

I am thinking that the "exists" API is not all that helpful. The only exception would be if there is a specific use case where an existence check must be made independent of retrieving the data.

Also, bear in mind that your API should not leak exception information. If there is a data retrieval error in the database, your service should map it to a client-friendly exception of some kind.