API Endpoint

Origin & evolution

The endpoint as a first-class design object grew out of the move to the web. Roy Fielding's 2000 doctoral dissertation, Architectural Styles and the Design of Network-based Software Architectures, introduced Representational State Transfer (REST) and argued that a distributed system should be organised around uniformly addressed resources, each identified by a URI and manipulated through a small, fixed set of methods. The endpoint is where that idea becomes concrete: GET /orders/42 names a resource and an operation in one breath.

The thinking has shifted as the constraints🔒ConstraintStrategyA constraint entityView reference → changed. REST treats the endpoint as a resource you act on; the rise of mobile and microservices exposed its weaknesses, such as over-fetching and chatty round trips. GraphQL collapsed many resource endpoints into one query endpoint, and gRPC reframed the unit as a typed remote procedure. The industry response was the OpenAPI Specification, which made the endpoint a machine-readable, versioned artefact that tooling could validate, mock, and generate clients from. The endpoint stopped being an implementation detail and became a published interface with its own lifecycle.

How it works in practice

A payments team owns a service⚙️ServiceEngineeringA deployable service or microserviceView reference → called checkout-api. One of its endpoints is POST /v2/charges. The contract is explicit: it accepts an amount in minor units, a currency, and an idempotency key; it returns a charge object or a typed error. The team measures this single endpoint at the 99th percentile latency and tracks its error rate separately from the rest of the service, because a slow /charges costs revenue while a slow /health costs nothing.

When a mobile client starts sending amounts as decimals, the endpoint rejects them with a 422 and a machine-readable error code. The breakage is contained to one endpoint and one contract version. The team ships v3 alongside v2, deprecates the old route with a sunset header, and watches the traffic migrate. Nothing else in the service has to change, because the endpoint is the boundary.

API endpoint vs. its neighbours

• Service is the deployable unit that owns and runs the code; an endpoint is one of the doors that unit exposes. A service can serve dozens of endpoints, and the same logical endpoint can be served by a fleet of service instances behind a load balancer.
• API contract🤝API ContractEngineeringAn API contract or specificationView reference → is the full specification: every endpoint, every schema, the auth model, the error catalogue. The endpoint is one entry in that contract. The contract is what you publish and version; the endpoint is what you call.
• Feature⭐FeatureProduct SpecificationA product capability or featureView reference → is product-facing capability💪CapabilityStrategyAn ability that enables value deliveryView reference → a user perceives, such as one-click checkout. An endpoint is the machinery behind it. One feature often spans several endpoints, and one endpoint can power several features.

In the graph

In the Unified Product Graph, api_endpoint🔌API EndpointEngineeringA specific API endpoint is a leaf in the Engineering and Platform region, whose anchor is the service⚙️ServiceEngineeringA deployable service or microserviceView reference →. Two hierarchy edges place it: service_serves_api_endpointServiceservesAPI Endpointhierarchy ties it to the running service, and api_contract_contains_api_endpointAPI ContractcontainsAPI Endpointhierarchy ties it to the published contract, so the same endpoint sits under both the thing that runs it and the thing that documents it. The cross-domain edge api_endpoint_serves_featureAPI EndpointservesFeaturecross-domain reaches into Product and Delivery, which is what lets you ask the query no single tool answers: if this endpoint breaks, which user-facing features go dark?