Dfyjkt

My team had a discussion early this week about if HTTP Codes should represent Business Failures.

Imagine a scenario where we have a Customer REST API. Within that API, we have lots of operations, like:

• 
  POST - mydomain.com/customers (receive a JSON body and create a new Customer)


• 
  GET - mydomain.com/customers/id (search for a specific Customer)


• 
  PATCH - mydomain.com/customers/id (receive a JSON body and patch a specific Customer)


• 
  DELETE - mydomain.com;customers/id (deletes a specific Customer)

Now, imagine a situation where I'm looking for a Customer which has the id = 5.

There's no Customer with the id = 5. What should I do in terms of HTTP status code?
Customer not found is a Business Failure. Should I return a 404 - NOT FOUND? Should I return a 200 - OK (with a JSON body describing that the Customer with ID 5 do not exist)?

We had a discussion exactly on that behavior.

Controller.java (example)

@GetMapping("/customers/id")
public ResponseEntity<?> handleRequestOfRetrieveCustomerById(@PathVariable("id") Integer id) throws CustomerNotFoundException 
 try 
 ResponseEntity.ok(customerService.findCustomerById(id));
 catch(CustomerNotFoundException e) 
 // log at Controller level and rethrow
 throw e;
 

Handler.java (example)

@ExceptionHandler(BusinessResourceNotFoundException.class)
@ResponseBody
protected ResponseEntity<Fault> handleExceptionOfBusinessResourceNotFound(BusinessResourceNotFoundException exception) 
 return new ResponseEntity<Fault>(exception.getFault(), HttpStatus.NOT_FOUND);

In this example, a 404 - NOT FOUND is returned with a body giving more details to the client.

From reading the HTTP/1.1 Specification:

404 Not Found

The server has not found anything matching the Request-URI. No

indication is given of whether the condition is temporary or

permanent. The 410 (Gone) status code SHOULD be used if the server

knows, through some internally configurable mechanism, that an old

resource is permanently unavailable and has no forwarding address.

This status code is commonly used when the server does not wish to

reveal exactly why the request has been refused, or when no other

response is applicable.

If "The server has not found anything matching the Request-URI...", I understand that returning a 404 - NOT FOUND would be the correct approach., since the /id composes my URI (mydomain.com/customers/id)

Am I right?

Which one is the better / right (if there's a wrong way) approach?

Status codes are meant to describe the result of the server's attempt to understand and satisfy the client's corresponding request.

Ultimately, if a client requests a representation of a resource that doesn't exist, the server should return 404 to indicate that. It's essentially a client error and should be reported as such.

Returning 200 would be misleading and would cause confusion to API clients.

Sometimes the HTTP status codes are not sufficient to convey enough information about an error to be helpful.

The RFC 7807 was created to define simple JSON and XML document formats to inform the client about a problem in a HTTP API. It's a great start point for reporting errors in your API. It also defines the application/problem+json and application/problem+xml media types.

Technically and from the http point of view, 404 should also be returned for any misspelling of the entity name (cutsomer instead of customer).

So even if you decide that "customer not found" will result in http 404, you cannot conclude that http 404 will imply "entity occurrence not found".

HTTP codes exist for a reason. Whoever consumes your API should be able to handle the response straight away, without having to result on the body contents.

In your case, 404(Not Found) looks quite suitable.

Alternatively, if you always return a 200, doesn't that beat the purpose of a response code altogether? If you are getting a response, you already know that your request got through to some extent.

TLDR;

Use 404 :)

I have recently worked on a Rest API with Spring Boot and the best practices found on the internet said this :

• Parameters null or value not set : 400 / Bad request
  


• Returned value not found (record or list empty) : 404 / Not found
  


• Exception from server (database error, network error etc.) : 500 / Internal server error
  

Those links will help you : best practice error handling, ControllerAdvice, error message

A REST API is part of the integration domain, not the business domain. It's a skin that your domain model wears to disguise itself as a web site aka an HTTP compliant key value store.

Here, 404 is an appropriate choice because it mimics the response that would be returned by a key value store if you tried to get a key that wasn't currently stored.

I would follow the meaning of HTTP status codes.

Wiki says (https://en.wikipedia.org/wiki/List_of_HTTP_status_codes):

This class of status code is intended for situations in which the error seems to have been caused by the client

So to be clear: mydomain.com/customers/id is a valid URL an the server understands the request. The fact that customer with id=5 doesn't exists has nothing to do with a "false URL" or "not understandable request".

In my opinion this should return some 2xx status code with further information inside json (definitions made by your REST API)