86 lines
4.5 KiB
Plaintext
86 lines
4.5 KiB
Plaintext
When building a https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api[REST API], https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/routing?view=aspnetcore-8.0#attribute-routing-with-http-verb-attributes[it's recommended] to annotate the controller actions with the available https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.routing.httpmethodattribute[HTTP attributes] to be precise about what your API supports.
|
|
|
|
== Why is this an issue?
|
|
|
|
- **Ambiguity**: Without HttpAttributes, it's unclear which HTTP methods an action method should respond to. This can lead to confusion and make the code harder to understand and maintain.
|
|
|
|
- **Unsupported HTTP Methods**: If an action is not annotated at all or is annotated only with the https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.routeattribute[Route attribute], it accepts all HTTP methods even if they are not supported by that action, which leads to further confusion.
|
|
|
|
- **Problems with Swagger**: https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger[Swagger] relies on HttpAttributes to generate parts of the API documentation. These attributes are necessary for the generated documentation to be complete.
|
|
|
|
- **Route path conflicts**: Without HttpAttributes, it's possible to accidentally create action methods that respond to the same route and HTTP method. This can lead to unexpected behavior and hard-to-diagnose bugs.
|
|
|
|
- **Lack of routing flexibility**: The HTTP attributes allow you to define multiple action methods in the same controller that respond to the same route but different HTTP methods. If you don't use them, you might have limited flexibility when designing your API.
|
|
|
|
== How to fix it
|
|
|
|
You should annotate the controller actions with the available HttpMethod attributes. You can still use them in conjunction with the Route attribute, in case there are multiple templates for one action and you need to https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.routeattribute.order?view=aspnetcore-8.0[set the order]. This allows you to clearly define the HTTP methods each action method should respond to, while still being able to customize your routes.
|
|
|
|
== Exceptions
|
|
|
|
This rule does not raise if the controller or the action is annotated with `[https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.apiexplorersettingsattribute[ApiExplorerSettings](IgnoreApi = true)]` or https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.acceptverbsattribute[`AcceptsVerbs` attribute].
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,csharp,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
[Route("Customer")] // This route conflicts with GetCustomers action route
|
|
public async Task<IResult> ChangeCustomer([FromBody] CustomerData data) // Noncompliant
|
|
{
|
|
// ...
|
|
return Results.Ok();
|
|
}
|
|
|
|
[Route("Customer")] // This route conflicts with ChangeCustomer action route
|
|
public async Task<string> GetCustomers() // Noncompliant
|
|
{
|
|
return _customerRepository.GetAll();
|
|
}
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,csharp,diff-id=1,diff-type=compliant]
|
|
----
|
|
[Route("Customer")]
|
|
[HttpPost]
|
|
public async Task<IResult> ChangeCustomer([FromBody] CustomerData data) // Compliant
|
|
{
|
|
// ...
|
|
return Results.Ok();
|
|
}
|
|
|
|
[HttpGet("Customer")]
|
|
public async Task<string> GetCustomers() // Compliant
|
|
{
|
|
return _customerRepository.GetAll();
|
|
}
|
|
----
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/routing[Routing to controller actions in ASP.NET Core]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/aspnet/core/mvc/controllers/routing#attribute-routing-with-http-verb-attributes[Attribute routing with Http verb attributes]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle[Get started with Swashbuckle and ASP.NET Core]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors#exception-handler[ASP.NET Core Exception handler]
|
|
* Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.mvc.routeattribute[RouteAttribute Class]
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
REST API controller actions should be annotated with the appropriate HTTP verb attribute.
|
|
|
|
=== Highlighting
|
|
|
|
* Action method identifier
|
|
|
|
endif::env-github,rspecator-view[] |