What is the correct status code to return for a successful PUT operation performed by a RESTful API?

In Visual Studio 2017, when creating a new controller for a .Net Core 2.1 Web API, and using the "Add Scaffold - API Controller with actions, using Entity Framework" wizard, the generated controller code returns a NoContent() for the PUT action, and a CreatedAtAction() for the POST action.

// POST: api/Items
[HttpPost]
public async Task<IActionResult> PostItem([FromBody] Item item)

if (!ModelState.IsValid)
return BadRequest(ModelState);

_context.Item.Add(item);
await _context.SaveChangesAsync();

return CreatedAtAction("GetItem", new id = item.Id , item);


// PUT: api/Items/5
[HttpPut("id")]
public async Task<IActionResult> PutItem([FromRoute] int id, [FromBody] Item item)

if (!ModelState.IsValid)
return BadRequest(ModelState);

if (id != item.Id)
return BadRequest();

_context.Entry(item).State = EntityState.Modified;

try

await _context.SaveChangesAsync();

catch (DbUpdateConcurrencyException)

if (!ItemExists(id))
return NotFound();
else
throw;


return NoContent();



I completely agree with the return value for the POST action. But regarding the PUT action returning a NoContent() with an empty body, is this "best practice" for RESTful APIs? I mean, I understand that it is returning a NoContent() status code because the body is empty, but would it not make more sense if it returned an Ok() to signal that everything went fine? It seems a bit ambiguous as to whether the action succeeded or not when receiving a NoContent() status code. Or is it more correct to return NoContent(), to let the consuming app know that it should ignore the body, and assume that, because no error code was returned, everything went fine?

Just wondering what RESTful best practice dictates in this situation...

1 Answer
1

Returning no content status still falls within the 2xx status code range which all indicate successful processing of the request. Returning 200 would now be just a matter of choice rather than what best practice dictates in this situation.

Reference Learn REST: A RESTful Tutorial - Using HTTP Methods for RESTful Services

PUT is most-often utilized for update capabilities, PUT-ing to a
known resource URI with the request body containing the newly-updated
representation of the original resource.

However, PUT can also be used to create a resource in the case where
the resource ID is chosen by the client instead of by the server. In
other words, if the PUT is to a URI that contains the value of a
non-existent resource ID. Again, the request body contains a resource
representation. Many feel this is convoluted and confusing.
Consequently, this method of creation should be used sparingly, if at
all.

Alternatively, use POST to create new resources and provide the
client-defined ID in the body representation—presumably to a URI that
doesn't include the ID of the resource (see POST below).

On successful update, return 200 (or 204 if not returning any content
in the body) from a PUT. If using PUT for create, return HTTP status
201 on successful creation. A body in the response is
optional—providing one consumes more bandwidth. It is not necessary to
return a link via a Location header in the creation case since the
client already set the resource ID.

PUT is not a safe operation, in that it modifies (or creates) state on
the server, but it is idempotent. In other words, if you create or
update a resource using PUT and then make that same call again, the
resource is still there and still has the same state as it did with
the first call.

If, for instance, calling PUT on a resource increments a counter
within the resource, the call is no longer idempotent. Sometimes that
happens and it may be enough to document that the call is not
idempotent. However, it's recommended to keep PUT requests idempotent.
It is strongly recommended to use POST for non-idempotent requests.

Thanks for contributing an answer to Stack Overflow!

But avoid …

To learn more, see our tips on writing great answers.

Required, but never shown

Required, but never shown

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.