csharp-api-controller-standards

C# ASP.NET Core API Controller Standards

Description

Defines the coding standards, patterns, and conventions for ASP.NET Core REST API controllers. Rules cover routing, HTTP verbs, response types, XML documentation, dependency injection, and asynchronous execution. Apply these rules uniformly to ensure a consistent, predictable, and well-documented API surface.

---

1. Controller Structure & Inheritance

1.1 Base Class and Attributes

• All API controllers must inherit from ControllerBase (not Controller, which includes view rendering logic).
• Decorate all controllers with the [ApiController] attribute to enable automatic model validation, API behavior conventions, and attribute routing requirements.
• Use the [Route] attribute at the class level to define the base path.

// ✅ Correct
[ApiController]
[Route("api/[controller]")]
public sealed class OrdersController : ControllerBase
{
}

// ❌ Wrong
public class OrdersController : Controller { }

---

2. Routing Conventions

2.1 Resource Naming

• Use nouns, not verbs, for endpoint paths.
• Prefer [controller] in the Route attribute to automatically use the controller name (minus the "Controller" suffix).

2.2 Route Parameters

• Specify route parameters explicitly in the HTTP verb attributes.
• Match route parameter names exactly with the method parameter names.

[HttpGet("{id:guid}")]
public async Task<IActionResult> GetByIdAsync(Guid id, CancellationToken cancellationToken)

---

3. HTTP Methods & Attributes

3.1 Standard Verbs

Use the correct HTTP verb corresponding to the operation:

Verb	Usage	Idempotent
[HttpGet]	Retrieve a resource or collection	Yes
[HttpPost]	Create a new resource or execute an action	No
[HttpPut]	Fully update an existing resource	Yes
[HttpPatch]	Partially update an existing resource	No
[HttpDelete]	Remove a resource	Yes

3.2 Action Parameters Binding