If I want to return a status code of 303 See Other when a client POSTs data that already exists, am I allowed to return that data in the content (body) of the response (in addition to setting Location), or must the client then GET the Location?
I would like to avoid requiring the client HTTP to make two HTTP calls if at all possible.
Idiomatically, the client should retrieve the data with a GET request.
Related
Is there a "REST-way" by which a client of a REST-API can indicate whether it is interested in getting a resource representation of the created resource in the POST response or whether it is just interested in HTTP response code (i.e. 201 on success) and location header?
I was thinking on using the Accept header. If the client adds a media type to this header that is supported by the API, the representation will be returned. Otherwise, it will just get a HTTP Created and the location header.
Context: The API will have to types of clients. A Web-UI client, that wants the representation in the response to save a network round-trip. And backend-service clients that will create resources at high rate in fire-and-forget manner. They're only interested in response code and resource URI.
There is a HTTP header:
Prefer: return=representation
The server can signal that it respected the header by returning:
Preference-Applied: return=representation
https://www.rfc-editor.org/rfc/rfc7240
I have an endpoint that requires a parameter passed via the query string (is a GET verb).
What is the appropriated status code to give when this parameter is missing from the request? 400 is the one? or should I respond with a 404?
[GET /search?q=ok] => 200 OK
[GET /search] => 400 Bad Request? or 404 Not Found? Or 422 Unprocessable Entity? Others?
TLDR It's an HTTP 400 - Bad Request.
It's a 400 because the user did not send the Required input field.
why not 422 - because this case fits to 400. Keeping your consumers in mind, you shouldn't go to non-popular response codes if you don't really need to.
Cases for HTTP 404:
Url which the client requested is not existing in your server (usually this will be handled by your server. Application developer usually doesn't have to do anything unless you want a nice looking 404 page or for SEO reasons).
If it was a path parameter and client was looking for an entity with an id (for Example (/students/{id} and your application couldn't find such entity, you may respond with an HTTP 404.
Let's say, user send the query parameter and you did not find any items matching the query param, make no mistake, it's still an HTTP 200 with body as an empty array or so (not a 404 unlike mentioned in the previous case). Example: /customers?lastname=unobtanium
It should be 400 - Bad Request.
The request could not be understood by the server due to malformed
syntax. The client SHOULD NOT repeat the request without
modifications.
404 - Not Found
The HTTP 404 Not Found Error means that the webpage you were trying to
reach could not be found on the server. It is a Client-side Error
which means that either the page has been removed or moved and the URL
was not changed accordingly, or that you typed in the URL incorrectly.
Its means server is not able to find the URI you specified. but in your case URI is valid but parameters are missing so 400 is right way to do it.
What is the appropriated status code to give when this parameter is missing from the request? 400 is the one? or should I respond with a 404?
I would argue that 404 is appropriate
The 404 (Not Found) status code indicates that the origin server did
not find a current representation for the target resource or is not
willing to disclose that one exists.
The fact that your routing implementation happens to send /search and /search?q=ok to the same handler does not mean that they are the same resource. /search identifies a resource, there's no current representation available for it, so you send a response back to the consumer explaining the problem, and put 404 in the meta data.
The big hint in the spec is this one:
A 404 response is cacheable by default
That lets us inform the client (and any intermediary components) know that this response can be reused.
It's a useful property, and it doesn't apply (out of the box) to 400 Bad Request
Heuristic: your web api should act like a document store. If you ask a document store to give you a document, but you spell the key wrong, what do you get? Some flavor of KeyNotFound exception. Same thing you would get if you asked a web server for a document in your home directory, but your spelled the file name incorrectly.
The semantics of the response indicate the right status code to use, not the implementation details.
Say I have a REST API with endpoint /api/users/. POSTing a user to that endpoint would create a new user and add it to the existing collection, give the user a unique ID so that you can work with it. If I make a GET /api/users/1, this should return me the created user with id: 1. My question is what should be the case for POSTing to a single item instead. For POSTing to a collection, you should return 201 Created if the resource was created, or a 409 Conflict if the resource already exists. What is the best practice for POSTing to a single resource ? Should it return a 405 Method Not Allowed, as you shouldn't be allowed to POST to a single resource or should it return a 404 Not Found as described here ?
If, at the moment a request is received, a resource (regardless of the concept that it represents) does not support a particular method (POST), the correct response to return is 405
The 405 (Method Not Allowed) status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource's currently supported methods.
The HTTP Specification includes a method (OPTIONS) and response headers (Allow) that enable a client to interrogate a server to discover what methods are permitted. Adoption might be lacking, although I suppose CORS changes that.
Note: there are use cases where POST to a singular resource is a reasonable option (consider how you would define the protocol to star a responsitory in an api where HTML was your hypermedia format). In that case, you should choose the appropriate success code (200, 201, 204...), assuming things went well, of course.
If someone tries to POST to a specific item where it should have call PUT to update. In my opinion 404 should be correct return status code, it tells the client that the resource they are looking is unavailable, which means the URL they are hitting isn't correct.
405 method not allowed should be invoked when client is hitting the right URL with wrong method type. suppose you have /api/users/{id} with PUT, but client is using POST.
I have a request from the client - when the user performs an action, there can be 3 actions:
the action succeeds with 200 OK status
the action fails (400) with an error message
the action succeeds but we need to display a helpful warning message to the user. This happens when the allocated amount is almost used up.
There does not seem to be a way for REST APIs to return an indication that the action completed successfully with some helpful information that further action might fail.
Thanks
HTTP response codes are limited and I think, those to be used to indicate any generic response. To have application specific response codes or response strings, it is better to have application level response codes to be communicated via HTTP response payload.
You didn't mention which HTTP method you are preparing for. Using GET should of course not modify anything, so I'm assuming it's either POST or PUT.
For POST, the response should be 201 Created. There should be a Location header line indicating the resource that was created.
For PUT, the response should be 200 OK.
In both cases, you can return a content body, as others suggested. This body can be some status information about the current state of whatever resource you are using. Note, that this status information might be reachable explicitly by some other URI, so it can share a mime-type with that "status" resource.
REST is using HTTP methods and HTTP status to represent the status of reply, by checking HTTP status I can find code 203 I think it could be suitable for your 3rd case :
203 Non-Authoritative Information (since HTTP/1.1)
The server successfully processed the request, but is returning information that may be from another source.
A PUT requests can have many outcomes, and I was wondering which status code would be best for each of them.
Say I want to create a new resources, so I do something like that:
PUT http://example.com/resources/resource-1
And I would get a HTTP 201 because a new resource has been created.
Now I want to update this resource, so I do the same request, with new contents:
PUT http://example.com/resources/resource-1
And I get HTTP 200 or HTTP 204, because the resource has been updated. But what if I send this request once again with the same contents? Should the server return HTTP 200 or HTTP 204 even if nothing has been updated?
I am aware that HTTP 200 and HTTP 204 both just mean that the request was successfully processed, and even if the data don't change the request can (and should) still be successfully processed. But is there a way to tell the client that the request has been successfully processed but nothing has changed on the server side? And if there is, should it be used for a PUT request? PUT being idempotent, should different status be returned depending on the actual processing on the server side (as long as no error occurs during this processing)?
But is there a way to tell the client that the request has been successfully processed but nothing has changed on the server side?
Yes, but that's not what status codes are for.
Either return 200 OK and a representation of the entity, or 204 No Content and return nothing.
For no change being applied, use a header like ETag. The client can compare the ETag with their previous value, and determine nothing was changed.