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...
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.