REST API reponses with HTTP response codes

Question

I am creating a REST API and I have faced a dilemma about HTTP responses. I found only 1 thread here which looked like the same question but the selected answer was not very clear to me.

For example I have an API endpoint which checks if a user with X e-mail address exists. So there can be 3 outcomes.

1- X exists (200)
2- X does not exist (404)
3- X has invalid syntax etc. (400)

Now when web server returns, should it always return with code 200 but the response body should have the error code related to the error? or http server also should return response with the code + body will have the API response?

The dilemma is that from point of HTTP, the request was satisfied perfectly. So in my opinion the response code should be 200 but API response should include code related to the operation result. Is this the way to go? For example HTTP response 200 + JSON response with content error 404 if user does not exist?

Do you know how this is handled in community packages such as FOSRestBundle?

Thanks!

Answer 1

Now when web server returns, should it always return with code 200 but the response body should have the error code related to the error? or http server also should return response with the code + body will have the API response?

If you review the HTTP specification, you'll see that the response body for an error is expected to explain the problem to the consumer in most cases. For example, the specification of the 4xx Client Error class states

Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

The response status codes are meta data, that provide a (coarse) understanding of the semantics of the response body, so that generic components (browsers, proxies, caches) can participate intelligently in the exchange. For instance, not only does 404 Not Found describe cases where the server was unable to find a current representation of a resource, it also informs the participants that the resulting representation is cachable by default.

Thus, your flow for figuring out what status code to you should normally be to first identify the semantics of the representation that you are returning in the the response body, and then to work out the correct meta data description of the representation.

Queries often give people trouble; a common misunderstanding comes from confusing a resource with a domain entity. The Not Found part of a 404 means that no current representation of the target resource was found; if what you are returning is a representation that describes no matches, then you shouldn't be sending a 404.

Example: think Google -- what status code do you get back when your search has no results? Or Atom Syndication -- if you invoke a GET request to list the current members of a collection, and the collection exists but currently has no members, then you should expect to get a success response and a representation of the collection with no member entries.

Answer 2

For example I have an API endpoint which checks if a user with X e-mail address exists. So there can be 3 outcomes.

Let the URL for such a request look like this:

https://example.com/api/v1/users/john.doe%40example.com

This API provides a collection resource of /users where a single user is identified by his email address like john.doe@example.com. The relevant path for of the URI for a user would look like /users/john.doe%40example.com.

A GET request for such an URL should return these HTTP status codes:

• 200 OK if a user with the email address exists.
• 404 Not Found if no such user exists.

I don't see a usecase for a response with the HTTP status code 400 Bad Request. Either a users exists or not. It does not matter if the email part of the URL path is a valid email address.

Answer 3

It depends on the client requirement on how you want to implement HTTP response code in your service. If you want your service to adhere to RESTful API conventions then using 200 for a successful response, 400 for a bad request, 404 for an object not found is the right way to go.

I would like to add that adding client logic in backend service is not a good idea as it tightly binds your backend with a specific client. In case you want to use the same API service to serve requests to an iOS client then you need the iOS client written in the same way you did for Android client. So its always better to keep client-specific logic on a client side and keep your REST API service as light as possible.