I'am writing an API to make users can subscribe to things. An user can subscribe to anything via submitting a POST something like this:
{
"item_id": "c13",
"requested_status": "subscriber",
"sure": true,
}
Here you can see a sure parameter. I'am using this to avoid making subscriptions accidentaly. If client sends that info without sure parameter API rejects that request to make GUI ask "are sure to subscribe this?". If user confirms, same post happens again with sure parameter. And subscription (or unsubscription) happens.
So, when I am rejecting that request because there is no sure parameter. Which response code should I use? I thought 400 (bad request) can be used but not sure.
Thanks for you response.
HTTP codes are codes with a pure technical meaning. What you want is not a technical problem and shouldn't be handled with technical means.
Since the reponse was received and contained technically correct values (not the same as functional valid values!), you should send a 200 - OK status. The content of your response should be the action to perform next. In this case, ask the user if he/she is sure.
If you work with Post-Redirect-Get, a 303 - See Other status is your best option.
Related
I've been under the impression that Post in Rest means "Create".
But after reading up on the spec http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5
It seems like it can be more than just Create?
That was also stated by Stormpath in their screencasts on rest api design.
According to Stormpath, Post means "Process" , which can be pretty much anything.
Is that the correct way to see it?
I can trigger custom actions for my resources using Post?
In theory, a POST request should attempt to create or modify some resource on the server. As #Tichodroma pointed out, an idempotent request will affect this change only the first time it is sent, but otherwise what's important is that some state on the server will be changed by the request.
More practically. POST requests are often used when the request payload is too large to fit into a GET URI (e.g. a large file upload). This is usually an intentional breach of HTTP standards to avoid a 414 Request-URI Too Long response.
In terms of verbiage, I don't know if I like "process", because even a GET request will usually be "processed" to determine the resource to return. The main difference in my mind is the change of some state on the server.
My users enter a few information fields in an iOS app.
This information must be validated on my server, which has a RESTful API.
After validation the UI of the iOS app changes to indicate the result.
Neither GET, PUT, or POST seem to be appropriate, because I'm not getting a resource, and neither is a resource created or updated.
What is the best fitting REST operation to implement this validation?
I use the same scenario as you and use PUT for it. You have to ask yourself: "when I send the same request twice, does this make a different state on server?" If yes, use POST, if no use PUT.
My users enter a few information fields in a iOS app. This information
must be validated on my server, which has a RESTful API. After
validation the UI of the iOS app changes to indicate the result....I'm
not getting a resource, and neither is a resource created or updated.
Since you aren't saving anything (not modifying any resource), I'd think this is technically more RPC than RESTful to me.
The following is my opinion, so don't take it as gospel:
If the information is simply being submitted and you're saying yes or no, and you're not saving it, I'd say POST is fine..
If information were actually being saved / updated, then choosing the proper HTTP method would be a lot more relevant.
POST = CREATE / SUBMIT (in an RPC context)
PUT = UPDATE (or CREATE if there is nothing to UPDATE)
I recommend using a ValidationResource and two requests. Each instance of this resource represents the validation of a set of data. The workflow:
1. Create new ValidationResource
Request: POST /path/to/validations
data to validate as the body
Response: 201 Created
Location: /path/to/validations/<unique-id-of-this-validation>
2. Look up result
Request: GET /path/to/validations/<unique-id-of-this-validation>
Respons: 200 OK
body: {'valid': true} or {'valid': false}
This is a RESTful approach in which the Validation is a Resource with server state.
Google proposes use of Custom Methods for REST API
For custom methods, they should use the following generic HTTP
mapping:
https://service.name/v1/some/resource/name:customVerb
The reason to use : instead of / to separate the custom verb from the
resource name is to support arbitrary paths. For example, undelete a
file can map to POST /files/a/long/file/name:undelete
Source: https://cloud.google.com/apis/design/custom_methods
So for validation the URL should be POST /resource:validate
I believe it is similar to GET entity but since we need to send data to validate and sending confidential data in URL is wrong habit as only payload data is ciphered by TLS, the only way left is POST or PUT.
However you may save or update the data in validate(eg. "verified":false). Based on requirement, you can go for POST or PUT (recommended POST if no update)
POST /user/validate-something
It seems like you're not doing it the correct way, if the validation is at the server-side then it should happen while submitting the data using a POST method. Then you'll validate that data, if validation fails then you can raise a 400 BAD REQUEST error, else you can create the resource.
This approach is more RESTful, as the POST method is properly used to create a resource or to raise 400 if validation fails
I just spent 20 minutes debugging some (django) unit tests. I was testing a view POST, and I was expecting a 302 return code, after which I asserted a bunch database entities were as expected. Turns out a recently merged commit had added a new form field, and my tests were failing because I wasn't including the correct form data.
The problem is that the tests were failing because the HTTP return code was 200, not 302, and I could only work out the problem by printing out the response HTTP and looking through it. Aside from the irritation of having to look through HTML to work out the problem, a 200 seems like the wrong code for a POST that doesn't get processed. A 4xx (client error) seems more appropriate. In addition, it would have made debugging the test a cinch, as the response code would have pointed me straight at the problem.
I've read about using 422 (Unprocessable Entity) as a possible return code within REST APIs, but can't find any evidence of using it within HTML views / handlers.
My question is - is anyone else doing this, and if not, why not?
[UPDATE 1]
Just to clarify, this question relates to HTML forms, and not an API.
It is also a question about HTTP response codes per se - not Django. That just happens to be what I'm using. I have removed the django tag.
[UPDATE 2]
Some further clarification, with W3C references (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html):
10.2 Successful 2xx
This class of status code indicates that the client's request was successfully received, understood, and accepted.
10.4 Client Error 4xx
The 4xx class of status code is intended for cases in which the client seems to have erred.
10.4.1 400 Bad Request
The request could not be understood by the server due to malformed syntax.
And from https://www.rfc-editor.org/rfc/rfc4918#page-78
11.2. 422 Unprocessable Entity
The 422 (Unprocessable Entity) status code means the server
understands the content type of the request entity (hence a
415(Unsupported Media Type) status code is inappropriate), and the
syntax of the request entity is correct (thus a 400 (Bad Request)
status code is inappropriate) but was unable to process the contained
instructions. For example, this error condition may occur if an XML
request body contains well-formed (i.e., syntactically correct), but
semantically erroneous, XML instructions.
[UPDATE 3]
Digging in to it, 422 is a WebDAV extension[1], which may explain its obscurity. That said, since Twitter use 420 for their own purposes, I think I'll just whatever I want. But it will begin with a 4.
[UPDATE 4]
Notes on the use of custom response codes, and how they should be treated (if unrecognised), from HTTP 1.1 specification (https://www.rfc-editor.org/rfc/rfc2616#section-6.1.1):
HTTP status codes are extensible. HTTP applications are not required
to understand the meaning of all registered status codes, though such
understanding is obviously desirable. However, applications MUST
understand the class of any status code, as indicated by the first
digit, and treat any unrecognized response as being equivalent to the
x00 status code of that class, with the exception that an
unrecognized response MUST NOT be cached. For example, if an
unrecognized status code of 431 is received by the client, it can
safely assume that there was something wrong with its request and
treat the response as if it had received a 400 status code. In such
cases, user agents SHOULD present to the user the entity returned
with the response, since that entity is likely to include human-
readable information which will explain the unusual status.
[1] https://www.rfc-editor.org/rfc/rfc4918
You are right that 200 is wrong if the outcome is not success.
I'd also argue that a success-with-redirect-to-result-page should be 303, not 302.
4xx is correct for client error. 422 seems right to me. In any case, don't invent new 4xx codes without registering them through IANA.
It's obvious that some form POST requests should result in a 4xx HTTP error (e.g. wrong URL, lacking an expected field, failing to send an auth cookie), but mistyping passwords or accidentally omitting required fields are extremely common and expected occurrences in an application.
It doesn't seem clear from any spec that every form invalidation problem must constitute an HTTP error.
I guess my intuition is that, if a server sends a client a form, and the client promptly replies with a correctly-formed POST request to that form with all expected fields, a common business logic violation shouldn't be an HTTP error.
The situation seems even less defined if a client-side script is using HTTP as a transport mechanism. E.g. if a JSON-RPC requests sends form details, the server-side function is successfully called and the response returned to the caller, seems like a 200 success.
Anecdotally: Logging in with bad credentials yields a 200 from Facebook, Google, and Wikipedia, and a 204 from Amazon.
Ideally the IETF would clear this up with an RFC, maybe adding an HTTP error code for "the operation was not performed due to a form invalidation failure" or expanding the definition of 422 to cover this.
There doesn't appear to be an accepted answer, which to be honest, is a bit surprising. Form validation is such a cornerstone of web development that the fact that there is no response code to illustrate a validation failure seems like a missed opportunity. Particularly given the proliferation of automated testing. It doesn't seem practical to test the response by examining the HTML content for an error message rather than just testing the response code.
I stick by my assertion in the question that 200 is the wrong response code for a request that fails business rules - and that 302 is also inappropriate. (If a form fails validation, then it should not have updated any state on the server, is therefore idempotent, and there is no need to use the PRG pattern to prevent users from resubmitting the form. Let them.)
So, given that there isn't an 'approved' method, I'm currently testing (literally) with my own - 421. I will report back if we run into any issues with using non-standard HTTP status codes.
If there are no updates to this answer, then we're using it in production, it works, and you could do the same.
The POST returns 200 if you do not redirect.
The 302 is not sent automatically in headers after POST request, so you have to send the header (https://docs.djangoproject.com/en/dev/ref/request-response/#django.http.HttpResponse) manually and the code does not relay on data of the form.
The reason of the redirection back to the form (or whatever) with code 302 is to disallow browser to send the data repeatedly on refresh or history browsing.
I'm doing an AJAX call to set the username. If the username is already taken what HTTP code should I return?
You can use 409 Conflict.
Indicates that the request could not be processed because of conflict in the current state.
I would choose 422 Unprocessable Entity . Lot's of rails developers use this for all validation errors.
And yes, it is totally appropriate to evaluate the error status and render the error message with javascript. This is especially useful, if you are using the same actions for an API. Then your ajax requests are accessing the same API that you would expose to other developers.
There is no rule here, it is up to you. However, as #rationalboss said, it makes sense to return 200 with a message since the HTTP request has succeeded, the error is unrelated to the request.
400 errors mean the request itself was not correct in some way, like wrong verb or missing parameters.
The question here is about interpretation, both from software clients and from humans and it might be better to stay away from error codes when there is no HTTP error.
There is no HTTP Code for name already taken. Please see List of HTTP Status Codes.
If you are using AJAX calls to set the username, why not just show the error in HTML? This is more user-friendly as your visitors would know what the actual error means, instead of seeing some 4XX code.
Since the POST request in a POST/Redirect/GET (PRG) pattern returns a redirect (303 See Other) status code on success, is it at all possible to inform the client of the specific flavour of success they are to enjoy (eg. OK, Created, Accepted, etc.) as well as any appropriate headers (eg. Location for a 201 Created, which might conflict with that of the redirect)?
Might it be appropriate, for example, to make the redirected GET respond with the proper response code & headers that would be expected from the POST response?
The HTTP 1.1 spec says:
This method [303] exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource.
But doesn't offer any insight into the loss of the more usual status code and headers.
Edit - An example:
A client sends POST request to /orders which creates a new resource at /orders/1.
If the server sends a 201 Created status with location: /orders/1, an automated client will be happy because it knows the resource was created, and it know where it is, but a human using a web browser will be unhappy, because they get the page /orders again, and if they refresh it they're going to send another order, which is unlikely to be what they want.
If the server sends a 303 See Other status with location: /orders/1 the human will be taken to their order, informed of its existence and state and will not be in danger of repeating it by accident. The automated client, though, won't be told explicitly of the resource's creation, it'll have to infer creation based on the location header. Furthermore, if the 303 redirects somewhere else (eg. /users/someusername/orders) the human may be well accomodated, but the automated client is left drastically uninformed.
My suggestion was to send 201 Created as the response to the redirected get request on the new resource, but the more I think about it, the less I like it (could be tricky to ensure only the creator receives the 201 and it shouldn't appear that the GET request created the resource).
What's the optimal response in this situation?
Send human-targetted information in the response body as HTML. Don't differentiate on the User-Agent header; if you also need to send bodies to machines, differentiate based upon the Accept request header.
If you have control over the web server, how about differentiating between the Agent header ?
Fill it in something only you know of (a GUID or other pseudo-random thing) and present that one to the webserver from the automated client. Then have the webserver response with 201 / 303 accordingly.