Foundations
What APIs are, why API design is its own discipline, the network primitives every product engineer should know.
Most engineers learn APIs by using them — they consume someone else's REST endpoint, read the OpenAPI doc, and treat the contract as immutable. The Foundations topic flips that perspective: you are the one designing the contract. The product-architecture lens treats every API as a product surface, with users (developer or end-user), constraints (latency, throughput, evolvability), and a competitive bar set by the best APIs in the wild (Stripe, AWS, GitHub).
Before touching endpoints, you have to know the substrate. The Internet's narrow waist (IP), the latency-vs-throughput dimensions, the socket primitive every HTTP server stands on, and the Web's three-letter trio (URL, HTTP, HTML) all show up the moment you start making real trade-offs.
Key concepts
- An API is a contract between two systems — and a product surface for the consuming developer
- The narrow waist (IP) is the everything-over-IP-and-IP-over-everything pivot — API designers build on top
- Latency and throughput are orthogonal — optimising one without the other is the most common trap
- Sockets are the OS primitive underneath every HTTP server — you should know what they are
- API design is a discipline distinct from system design — it lives at the product surface, not the storage layer
Reference template
// Reasoning about a new API
1. Who's the user? (developer? end-user? both?)
2. What's the contract? (verbs, resources, payloads, errors)
3. What's the latency budget? (sum of processing, network, queueing)
4. What changes can it survive? (additive vs breaking, versioning model)
5. What does failure look like? (error taxonomy, retry semantics, partial success)
6. Who's monitoring it? (SLI / SLO / SLA, alerting paths)Adapt to your problem; the structure is the load-bearing part.
Common pitfalls
- Designing the endpoints before defining the consumer's use cases
- Confusing latency and throughput — they trade off against each other
- Building an API without an evolution story; v1 ages out of relevance
- Treating the API as a system-design problem (storage, scaling) instead of a contract-design problem
Related topics
Items (6)
- What Is API Design?
APIs as contracts between systems. The product-architecture lens, why API design is its own discipline, and what good looks like.
Concept Foundational - Business Considerations of APIs
APIs as products. Monetisation, partner programs, developer experience as a moat, why Stripe is Stripe.
Concept Foundational - The Narrow Waist of the Internet
Why IP is the everything-over-IP-and-IP-over-everything pivot, and what that means for API designers building on top.
Concept Foundational - Latency and Throughput
The two performance dimensions every API designer must hold in head. The 100 ms human-perception ceiling and the throughput-vs-latency trade.
Concept Foundational - Network Sockets — The Foundation
Sockets as the OS-level primitive every HTTP server stands on. Why API designers should know what's underneath.
Concept Foundational - The World Wide Web
URLs, HTTP, HTML — the three-letter trio Tim Berners-Lee picked in 1989 and the rest of API design has been catching up with since.
Concept Foundational