An endpoint is the address clients use to reach a service. It is part of the API contract: changing an address without a redirect can break clients. section 6.3.2
Design endpoints as clear, durable resource addresses:
- Prefer GET /api/v1/orders/123 to a verb-heavy route such as GET /api/getMyThings. section 6.10.1 section 6.3.2
- Give returned items identities and use extensible data structures, so clients can refer to individual items and new fields need not force a breaking type change. section 6.10.1
- Avoid multiplying routes for every small variation; a general endpoint with filtering can be easier to maintain. section 6.8.2
Listing 6.5 An Example of a Clean API Endpoint
[ApiController]
[Route("api/orders")] // The Menu Section
public class OrderController : ControllerBase
{
private readonly IOrderService _service; // The Core
public OrderController(IOrderService service)
{
_service = service;
}
// THE CONTRACT: GET /api/orders/{id}
[HttpGet("{id}")]
public async Task<IActionResult> GetOrder(int id)
{
// 1. Translate HTTP request to Domain intent
var order = await _service.GetOrderById(id);
// 2. Handle "Not Found" (Implicit Contract)
if (order == null)
return NotFound($"Order {id} not found.");
// 3. Translate Domain Object to HTTP Response (JSON)
return Ok(order);
}
}A C# controller exposes GET /api/orders/{id}, delegates the lookup to a service, and translates the result into a not-found response or JSON. section 6.7






























