Misleading Location Header in Examples for TypedResults.Created in ASP.NET Core Documentation?

[wesdoyle]

Description

In the Controller action return types in ASP.NET Core web API, the examples provided for setting the Location header in each of resource creation endpoints seem unconventional in that they reference the methods use to create the resource rather than the method used to read them.

Currently, the Location header is set referencing the controller method name for creating the resource in each example. E.g.,

[HttpPost()]
[Consumes(MediaTypeNames.Application.Json)]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync_IActionResult(Product product)
{
    // ...
    return CreatedAtAction(nameof(CreateAsync_IActionResult), new { id = product.Id }, product);
}

The Location header here refers to the CreateAsync_IActionResult action (POST method); it seems more conventional to reference a GET endpoint here, where the newly created resource could be accessed.

In other areas of ASP.NET Core documentation (For example, Tutorial: Create a web API with ASP.NET Core) the Location header is set using an example GET endpoint, which seems more aligned with Location semantics:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    // ...
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.2:

For 201 (Created) responses, the Location value refers to the primary
resource created by the request.

In many cases, this may result in a correct URI (both GET and POST endpoints being at the same URL with different HTTP verbs); however, I'm wondering if it wouldn't be more consistent to use a method name bound to a GET request, as in the example from the tutorial documentation. Thanks for your consideration.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-8.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/web-api/action-return-types.md

Document ID

b51bc104-a6e2-b21f-8362-45cee22e8c22

Article author

@tdykstra

Related Issues