Should I return a 204 or a 404 response when a resource is not found?

Question

I am developing a simple RESTful service for tournaments and schedules. When a tournament is created through a POST request containing a JSON body, the tournament is inserted in a BiMap, declared as follows in a DAO implementation:

private BiMap<String, Tournament> tournaments = Maps.synchronizedBiMap(HashBiMap.create());

When a tournament is created, its associated string id is returned so the user can have future reference of that tournament. He/she can get information back from the new tournament performing the following request:

GET http://localhost:8080/eventscheduler/c15268ce-474a-49bd-a623-b0b865386f39

But what if no tournament with such id is found? So far, I am returning a 204 response. Well, Jersey is doing it for me when returning null from one of its methods. This is the method that corresponds to the route above:

@Path("/{id}")
@GET
@Produces(MediaType.APPLICATION_JSON)
public Tournament getTournament(@PathParam("id") String id) {
    Optional<Tournament> optTournament = tournamentDao.getTournament(id);
    if (optTournament.isPresent())
        return optTournament.get();
    return null;
}

My question is: is it OK to return a 204: No Content response, or should it be a 404 response instead, since the resource was not found?

If I should change it to a 404, obvious question: I should change the method signature right? Since now a tournament (of type Tournament) might not be returned, the method should look different. Should I use the Response type as the return type instead?

Answer 1

HTTP 204 means that something was found, but it's empty. For instance, imagine that you're serving log files through HTTP, with the requests such as http://example.com/logs/[date-goes-here]. On May 18th, 2015:

• http://example.com/logs/2015-05-19 would return HTTP 404, which means that there are no logs, because, well, it's difficult to log the future.

• http://example.com/logs/2015-05-18, however, would return either HTTP 200 with the log entries in the content of the response, or HTTP 204 if the log file was created, but there are still no logs recorded yet for this date.

If you provide null to the framework as a response to a request, it assumes that you found an entry, and this entry is empty, thus HTTP 204. Instead, you should throw new NotFoundException(); to indicate to the framework that the entry doesn't exist, so that it would generate a HTTP 404.

If I should change it to a 404, obvious question: I should change the method signature right?

No, you don't. That's the nice thing about throw new NotFoundException();. It will work no matter what is the actual return type of your method.

Answer 2

You should return a 404. You can do it by throwing a NotFoundException (https://jersey.java.net/apidocs/2.6/jersey/javax/ws/rs/NotFoundException.html).

Also please look at this SO question if you need to control the returned content type https://stackoverflow.com/questions/23858488/how-i-return-http-404-json-xml-response-in-jax-rs-jersey-on-tomcat

Answer 3

Your request is GET http://localhost:8080/eventscheduler/c15268ce-474a-49bd-a623-b0b865386f39.

If http://localhost:8080/eventscheduler/ does not exist as an endpoint, you should return a 404. You are attempting to access a resource (/eventscheduler/) that does not exist. This would indicate to a client that a server exists on localhost:8080, but there's nothing at the eventscheduler endpoint.

If http://localhost:8080/eventscheduler/ exists as an endpoint but required resources are unavailable, a 5xx error is appropriate. A good example of this would be if a database is offline, where you could return a 503. Of course, you may just want to return a generic 500 error instead of a specific instance.

If http://localhost:8080/eventscheduler/ exists but the thing represented by c15268ce-474a-49bd-a623-b0b865386f39 does not exist, I would return a 200 with a body indicating the details. The endpoint exists, the request made was totally valid and could be processed, but there was no match.

If your client's request to the endpoint was not valid, you would look at the other 4xx errors. You can indicate that the client is not authorized to access the endpoint or the item(s) requested with a 401 or 403 or can use a 400 to indicate that the request is invalid. With any of these, additional information can be provided in the response body.