Should failed results be errors or data in RESTFul?

Question

Assuming I have a RESTful service and it always responds in this format:

{
    "error": { 
        "code": ...,
        "message": ...
    }
}

or

{
    "data": ...
}

and there is a method like POST /users/me/change-password.
What would be the correct and RESTful behavior:

1. Business logic / validation errors are data

   • Password has been changed (200, empty error and data)
   • User is not authenticated (401, error = 1, empty data}
   • Password policy: password has already been used (200, empty error, data = 1)
   • Password policy: password doesn't match requirements (200, empty error, data = 2)
   • SMS-OTP confirmation required (200, empty error, data = 3)
   • Incorrect SMS-OTP (200, empty error, data = 4)
   • The user has disabled password changing (200, empty error, data = 5)

   It seems correct since errors like "SMS-OTP confirmation required" are not even client errors. A client did nothing wrong, and expects an "OK" response.

2. Business logic / validation results are errors

   • Password has been changed (200, empty error and data)
   • User is not authenticated (401, error = 1, empty data}
   • Password policy: password has already been used (400, error = 2, empty data)
   • Password policy: password doesn't match requirements (400, error = 3, empty data)
   • SMS-OTP confirmation required (400, error = 4, empty data)
   • Incorrect SMS-OTP (400, error = 5, empty data)
   • The user has disabled password changing (400, error = 6, empty data)

   It seems correct since 200 OK status suggests that password has been changed succesfully, whatever written in response. However, some clients like C# WebClient do not even return non-OK responses, they just throw exceptions.

The same questions arise in terms of all authentication requests. For example, is "username is already occupied" for "sign-in" an error or data.

Answer 1

REST gurus will tell you that every possible error has an HTTP error code which maps to it.

However, before we get caught up in that madness, we should remember that throwing exceptions shouldn't be your first choice for returning data to the user.

In this case it seems to me that if you refactor your 'change password' method to return an object, or even just a bool half of those exceptions disappear.

I think this is the right choice for situations where you have multiple errors, such as password doesn't meet strong password criteria x, y, and z.

keep the exceptions for exceptional stuff ie. user not found or access denied.

This calls out the possible responses that the consumer should handle specifically and lets them leave (90% of) the exceptions to their default 'show error to user' handler.

---

Note: This is different from returning the exception as a json object with a 200 response code. Which should be avoided.

---

eg.

public class PasswordChangeResult
{
    public bool PasswordChanged;
    public List<string> ValidationErrors;
}

OR an HTTP error

is always returned.

Answer 2

Business logic / validation results are errors

This is the correct response for REST.

REST is state transfer. The client does something to a resource and transfers the new state to the server.

You should change the resource from /users/me/change-password to /users/me/password and the HTTP verb from POST to PUT.

The client is saying "Here is the new state of the users password, it is now this" and sends that message to the server. The server can either accept that state update, or reject it.

If the server rejects that update it should return an error. The client needs to know that the state transfer did not take place. But try not to think of HTTP 4xx response codes as having different meanings depending on your specific domain. They relate to the state transfer part of the communication, not the domain. Most deal with the mechanics of that state transfer (is your message syntactically correct, was there a network error, are you authenticated etc)

For example 400 means bad request from the point of view of the formatting of the HTTP request. If the request to the server was a perfectly valid HTTP request but the server is rejecting it for some business domain reason, it shouldn't reply 400

Often the correct response is 403 Forbidden when a business rule fails and the server rejects the state update request. If you think of it this way, the server is saying to the client "Everything is syntactically fine with this request, but I will now allow this update because of this reason", basically forbidding the update.

You might have

403 Forbidden Password has already been used

and

403 Forbidden Password doesn't match requirements

Both are valid. The 4xx are not designed to tell the client the specific domain reason that the server didn't do something. That is what the response body is for, and a client should understand both the general HTTP response codes and the specific messages of the response bodies