What Is an API

The Contract Definition

An API is a promise about behavior: given these inputs, in this state, this output follows. Everything else is implementation — free to change. The promise is the product boundary; the code behind it is negotiable.

 CLIENT                        CONTRACT (the API)              SERVER
 needs a stable thing ◄─────── resources + verbs + errors ───► free to refactor,
 to build against             + versioning rules               reshard, rewrite
 
 contract changes = coordinated migration across every consumer
 implementation change = invisible

This asymmetry drives everything in API design: contracts are expensive, implementations are cheap. Design effort goes into making the contract right.

APIs at Every Altitude

Layer	Example	Contract shape
System-to-system	RideShare ↔ payment PSP	REST/gRPC over network
Service-to-service	trip service ↔ location service	gRPC, events
Library	SDK, framework class	function signatures
Product surface	public developer platform	versioned REST + webhooks

Same discipline everywhere: explicit inputs/outputs, documented failure modes, evolution policy.

What Makes an API Good

Property	Test
Hard to misuse	Wrong usage fails loudly at first call, not in production
Consistent	Same concepts named/shaped the same way across endpoints
Complete error story	Every failure has a defined representation
Evolvable	Room to add without breaking (pagination, extra fields)
Observable	Callers can tell what happened (ids echoed, status precise)

Consistency deserves emphasis: an API is a language. Each endpoint teaching new grammar taxes every consumer; reusing established patterns (id, created_at, cursor tokens) makes the hundredth endpoint free.

Surface Area Is Liability

Every exposed field, parameter, and endpoint is a permanent maintenance obligation:

 exposing "internal_notes" on GET /users
 → some partner will scrape it within weeks
 → removing it now breaks them
 → you own that field forever

 rule: expose the minimum that enables the use case;
       adding later is cheap, removing is a deprecation project

Interview Framing

System design interviews increasingly include an API-design beat (“define the endpoints”). Strong candidates sketch 4–6 core endpoints with method, path, key request/response fields, and one error case each — then stop. Exhaustive CRUD enumeration wastes clock; the signal is shape judgment: which resources exist, what the identifiers are, where lists paginate.