ASP.NET Core Web API Interview Question #100

What are best practices for routing, versioning, and API documentation?

Routing, Versioning, OpenAPI/Swagger & API Documentation Mid-Level Intermediate

Quick Interview Answer

Use predictable resource-oriented routes, appropriate constraints, and URL generation instead of manually constructing links. Keep public routes stable and avoid unnecessary deep nesting or implementation-oriented action names.

Detailed Explanation

Version APIs when incompatible contract evolution requires it, preserve backward compatibility where practical, and use a clear deprecation process. Maintain accurate OpenAPI documentation with request/response schemas, status codes, authentication requirements, and useful descriptions so consumers can integrate without reading server implementation code.

Code Example

[ApiController]
[Route("api/v1/products")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id:int}", Name = "GetProductV1")]
    [ProducesResponseType<ProductResponse>(200)]
    [ProducesResponseType(404)]
    public async Task<ActionResult<ProductResponse>> Get(
        int id,
        CancellationToken token)
    {
        var item = await _service.GetAsync(id, token);
        return item == null ? NotFound() : Ok(item);
    }
}