6

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.

  • In case this question is more appropriate on Stack Overflow I will move it there. Just drop a comment thanks! – GibboK Sep 8 '16 at 10:03
8

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)?

5

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;
  • 1
    400 symbolizes a bad request. The message should define what input was incorrect and what input is expected. – superhero Sep 9 '16 at 8:29
  • you're right.. I'm editing the answer :) – FredMaggiowski Sep 9 '16 at 13:48
  • Also, you could add the case when a token is not provided. – AilurusFulgens Sep 9 '16 at 15:26
  • Well, it'd still a Bad Request hence the 400 status code. Specifying it might be better though. – FredMaggiowski Sep 9 '16 at 17:38
  • 1
    Yes, but even if it leads to return the same status, you still have to check ;) ! Consider also, in case of a 4xx status code, that problem details could be provided in the response body. A recent RFC (rfc-editor.org/rfc/rfc7807.txt) cover this needs. – AilurusFulgens Sep 9 '16 at 20:23

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.