liveBook · Manning

Endpoint

As explained in Grokking Software Architecture

A public endpoint is an externally reachable interface through which clients can send requests to a system or service.

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

How Grokking Software Architecture covers it

How deep it goes
Explains endpoint addresses, design pitfalls, and a controller example without detailing routing internals.
Examples
Uses order routes, a C# controller, verb-heavy URLs, and filtered user endpoints as examples.
What you can do after
Build a REST endpoint that delegates work to a service and translates results into HTTP responses.
How it connects
Connects endpoints to REST, HTTP methods, API contracts, controllers, and services.

Also explained in

Compare how 31 books explain endpoint →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.