Good practice for status code returned by restful API when validating a token

Question

I am working on client JavaScript SPA and a restful API on HTTPS.

Client application needs to call a public endpoint (no token required) in order to valid (GET) a specific TOKEN previously remember within the SPA application.

API returns:

• If token is valid a status code 200 is returned and a json value {"isValid": "true"}:
• If token is malformed a status code code 200 is returned and a json value {"isValid": "false"}:
• If token is unauthorized a status code code 200 is returned and a json value {"isValid": "false"}

I would like to know:

• Has the backed developer designed correctly API?
• For malformed token should API return instead a generic 400 (“Bad Request”) and for 401 (“Unauthorized”) for token which is not unauthorized.

Please note: This question is not the just about status code, my concern is regarding the design of a public endpoint which provide information to client application where the endpoint does not require authentication using token.

Answer 1

This depends on the purpose of the API.

If the purpose is validation of tokens, then returning 200 OK for successful requests seems sensible. A 4xx error would mean the usage of the validation API is incorrect, not that the token is invalid.

Things are different if the token manages access to this API. In that case, you don't need an endpoint to check whether the token is valid. The backend should check the access token on every request. Then, when a request fails because the token is invalid, I would expect a Not Authorised response.

Remember that REST APIs use HTTP as a transport. The actual data of your API is not expressed on a HTTP level, but in the bodies of the requests and responses. The HTTP headers and status codes can be used for metadata, authentication, and out-of-band error messaging.

There is an analogy to programming languages here: An API call is similar to a method call. The response contains a return value – the response body. But if the HTTP response has a 4xx or 5xx status, that is as if the method had thrown an exception and did not return normally.

So, your token validation: should it return true/false as a result (a 200 response with a body containing that data), or should it either return nothing or throw an exception (2xx response vs. 4xx response)?

Answer 2

You have status codes, you should use them :)

To me the developer hasn't designed correctly the APIs, since it should have used status codes as you suggested.

Hence if the request has a:

• Valid Token:

• Status code: 200;
• Body: not needed;

• Malformed (or missing) Token:

• Status code: 400;
• Body: JSON message providing informations about what was wrong in the input. {"errno": X, "error": "<error-message>"};

• Token valid but not authorized

• Status code: 401;
• Body: not needed.

As you can see a JSON body is not always needed, a REST API shouldn't rely just on JSON bodies, but use the whole HTTP(s) protocol semantics.

---

For reference about status codes take a look here and here.

@AilurusFulgens suggested this RFC. It's very helpful to clarify how to use JSON bodies with 4xx status code.

In summary:

• 2xx: are used when a request is successful;
• 3xx: are used to identify a redirection;
• 4xx: are used to provide informations about a client issue with the request;
• 5xx: are used to provide informations about a server issue with the request;