I have REST api with PUT method for updating resource ,I want to send 200 if resource is updated and 201 if resource is created from controller. Is it possible to return one of response code from one controller mapping depending upon resource is created or updated ?
I checked on internet but not able to find absolute answer
Related
If i have a post endpoint for a car, but only get endpoints for a collection of cars, what should be the created URL in the Response. Usually it should be cars/{id-of-new-car}
But since that endpoint does not exists, that URL is misleading.
If you only have a collection, and you used POST on that collection to add a new car, you didn't create any new resources, you just updated one (the collection).
So if your question is: What should go in the Location header that goes along with the 201 Created response, I'd say you probably don't need either.
I am implementing a RESTful API and an endpoint of one controller is Delete. Delete does two actions depending of the entity to be removed: it updates the entity or it deletes the entity from the database. If delete updates the entity I would send the HttpStatus 200 and the updated entity. But if the delete removes the entity from the database I would send only the HttpStatus 200. In one case I am returning an object. But in the other case, the object doesn't existe any more. Is it a good approach or I am missing anything?
Short answer
The suitable status codes for a DELETE request that has succeeded are 200, 202 and 204.
Long answer
DELETE does two actions depending of the entity to be removed: it updates the entity or it deletes the entity from the database. [...] Is it a good approach or I am missing anything?
The DELETE method is not meant for performing updates.
See the following quote from the RFC 7231, one of the documents the define the HTTP/1.1 protocol, for details on what the DELETE method is about:
4.3.5. DELETE
The DELETE method requests that the origin server remove the
association between the target resource and its current
functionality. In effect, this method is similar to the rm command
in UNIX: it expresses a deletion operation on the URI mapping of the
origin server rather than an expectation that the previously
associated information be deleted. [...]
If the delete operation has succeded, the server can return one of the following status codes:
202: Indicates that the request has been accepted for processing, but the processing has not been completed.
204: Indicates that the server has
successfully fulfilled the request and that there is no additional
content to send in the response payload body.
200: Indicates that the request has succeeded and the request payload includes a representation of the status of the action.
See the following quote from the same document:
If a DELETE method is successfully applied, the origin server SHOULD
send a 202 (Accepted) status code if the action will likely succeed
but has not yet been enacted, a 204 (No Content) status code if the
action has been enacted and no further information is to be supplied,
or a 200 (OK) status code if the action has been enacted and the
response message includes a representation describing the status.
The commonly considered HTTP Statuses for DELETE include:
200 OK (MDN)
202 Accepted (MDN)
204 No Content (MDN)
204 is ideal if your service is not returning any additional info. It is also popular for PUT update requests. Many services return 204 including Docker as shown below:
Ref: https://docs.docker.com/engine/api/v1.24/
However, if you are implementing HATEOAS, it is better to use 200 OK and provide some links for the service. Think of an application that has just issued a delete and needs to navigate a user to a location. Without providing a URL for that location, the client app needs to keep state. Providing a 200 OK with a link allows the REST API to keep state for the client.
The following article describes this issue well (read the blog for more discussion):
Avoid 204 responses if you're building a HATEOAS application.
This is a lesson about REST API design that I learned while building non-trivial REST APIs. In order to be as supportive of the client as possible, a REST API should not return 204 (No Content) responses.
From the service's perspective, a 204 (No Content) response may be a perfectly valid response to a POST, PUT or DELETE request. Particularly, for a DELETE request it seems very appropriate, because what else can you say?
However, from the perspective of a proper HATEOAS-aware client, a 204 response is problematic because there are no links to follow. When hypermedia acts as the engine of application state, when there are no links, there's no state. In other words, a 204 response throws away all application state.
If a client encounters a 204 response, it can either give up, go to the entry point of the API, or go back to the previous resource it visited. Neither option is particularly good.
Ref: http://blog.ploeh.dk/2013/04/30/rest-lesson-learned-avoid-204-responses/
Let's say we have a collection resource called shelf (of book resources) and we would like to POST a new book:
[POST] /shelves/{shelf-id}/books [request body -- a book]
I know that the response should be either empty with a reference to the newly created resource (201) or include the created resource (200).
Let's say the clients that are creating book resources, will need to show summary of the shelf the new book is added to. One solution should be making clients to first do a POST (let's call it Req#1 -- to create the new book), and then a GET (Req#2) on the shelf resource to get the summary.
What if we care a lot about efficiency and want to return the result of Req#2 implicitly when getting Req#1 on the server and save one request on the client side? Is it OK based on REST principles to return the parent collection resource information in the response when a resource is added to the collection?
Any alternative design?
It's 'OK' for REST design to return different resource states, but HTTP doesn't have a standard way to do this. If you uses the HAL format for you REST api, it does have a way to do embedding, so I suppose you could embed different resources to the response of a POST request.
Note that there's no standard I know of that suggests that the following statement is true: I know that the response should be either empty with a reference to the newly created resource (201) or include the created resource (200).
Anyway, what are you trying to solve? Is it really that expensive to do an extra HTTP request? Where do you base that concern on? What's expensive about it? Is it the latency of having to do an extra roundtrip?
If that's the case, you could consider using HTTP/2 push to push a new version of your parent resource. It's probably the most standards compliant way. If your server and client support this well, then this also means you can use this as a great standard mechanism to push things to clients because they might soon request it.
I know that the response should be either empty with a reference to the newly created resource (201) or include the created resource (200).
This isn't true. According to the spec:
The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code.
In summary, use a 201 status response with information about the new resource. Please don't mix information about other resources with it. That is not RESTful, and apart from pedantry, it probably will make a messy API for very little benefit.
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.
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.