However, that token doesn't include or imply any permission or scope that allows the client to perform the desired action. Assume, for example, that your client sends a request to modify a document and provides a valid access token to the API. On the other hand, if the client's request includes an expired access token, the API response could include the reason for the denied access, as shown in the following example: HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="example",Įrror_description="The access token expired" When to Use 403 Forbidden? If the client request does not include any access token, demonstrating that it wasn't aware that the API is protected, the API's response should not include any other information. You have to use the Bearer scheme and provide the realm parameter to indicate the set of resources the API is protecting. That comes in the form of the 401 Unauthorized WWW-Authenticate: Bearer realm="example" In the spirit of mutual collaboration between the client and the API, the response must include a hint on how to obtain such authorization. In both cases, the appropriate status code to reply with is 401 Unauthorized. An access token is expired, revoked, malformed, or invalid for other reasons.For example, in the OAuth context, this may fall in one of the following cases: Now, let's assume that the client calls your protected API with a well-formed request but no valid credentials. "detail": "Your request parameters are not valid.", However, using a standard format like the one proposed by the Problem Details for HTTP APIs specifications would be more appropriate to enable uniform problem management across clients.įor example, if your client calls your API with an empty value for the required data parameter, the API could reply with the following response: HTTP/1.1 400 Bad Request Content-Type: application/problem+json You can provide those details in the format you prefer, such as simple text, XML, JSON, etc. So, you should add in your response's body what was wrong with the client's request. In both cases, the client's request is not as expected and should be refused.įollowing the general principle discussed above, the client should be empowered to understand what to do to fix the problem. Your API should return the same status code even when the client provides an unsupported parameter or repeats the same parameter multiple times in its request. In fact, if that parameter is required, your API can't even process the client request. In this case, your API should respond with a 400 Bad Request status code. Let's start with a simple case: a client calls your protected API, omitting a required parameter. "The basic principle behind REST status code conventions is that a status code must make the client aware of what is going on and what the server expects the client to do next" Of course, you can use them even if you don't use OAuth to secure your API. What happens when the client has no appropriate credentials? What status code should your API return when a request is not legitimate? What information should it return, and how to guarantee the best security experience?įortunately, in the OAuth security context, you have some guidelines. If the client provides the appropriate credentials (e.g., a valid access token), its request is accepted and processed. Let's consider the case when a client attempts to call a protected API. In summary, your Web API's response should provide the client with enough information to realize how it can move forward opportunely. Similarly, when the client receives a 500 Internal Server Error status code, it knows that this is a problem on the server side, and the client can't do anything to mitigate it. If the client receives a 201 Created status code, it knows there was no problem with its request, but the resource representation is not in the response's body. For example, if the client receives a 200 OK status code, it knows there was no problem with its request and expects the requested resource representation in the response's body. This is a general principle that applies to all the HTTP status codes. If there is a problem, what should the client do?.If there is a problem, on which side is it? On the client or on the server side?.You can fulfill this principle by giving answers to the following questions: The basic principle behind these conventions is that a status code returned in a response must make the client aware of what is going on and what the server expects the client to do next. Although the vast majority of them don't actually implement REST, they usually follow a few RESTful conventions when it comes to HTTP status codes. Most Web APIs are inspired by the REST paradigm. Before going into the specific topic, let's take a quick look at the rationale of HTTP status codes in general.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |