--- title: "01 — What Even Is an API? The Model That Clicked" uid: what-is-an-api tags: ["architecture", "roadmap:api-design", "api", "http", "fundamentals"] excerpt: "An API is a contract, not a URL that returns JSON. The URL-returning-JSON shape is just one form the contract can take — and knowing the definition first makes every design decision downstream easier." date: 2026-08-13T03:28:35+0000 source: https://www.aveshina.my.id/en/blog/what-is-an-api --- "A URL that returns JSON" was my whole model of an API, and it took one definition to straighten it out: **an API is a contract, a deliberate surface a service exposes so other software can use it without knowing how it's built.** [2] The URL-returning-JSON thing is one shape that contract can take, not the definition. The framing that finally landed: an **Application Programming Interface** is the *interface* part doing the heavy lifting [1][2][3]. A service has internals — databases, business logic, file systems, private functions. Instead of forcing every consumer to learn those internals, the service carves out a small, stable set of operations and says "use these, and only these." That carve-out is the API. The consumer (another server, a browser app, a mobile client) talks to the surface, not the guts. Everything good about APIs — stability, security, evolvability — comes from that separation. ## The interface, not the implementation The cleanest analogy I found is a restaurant [2]. The kitchen is the service's internals — chaotic, full of specialized equipment, staffed by people following procedures a customer doesn't need to understand. The **menu** is the API. It lists what you can order (the operations), declares what each dish contains (the inputs and outputs), and hides how it's cooked. You don't walk into the kitchen; you order from the menu and a dish comes back. If the kitchen replaces its oven, the menu doesn't change — the interface stays stable while the implementation evolves underneath. ```figure ``` That picture is the whole thesis. The consumer never touches the dimmed boxes. It only ever calls the labeled knobs. ## Why we bother with one Once the separation exists, a pile of benefits fall out for free [1][3]: - **Stability.** The service team can rewrite the database, swap languages, or restructure internals — as long as the API surface keeps its contract, no consumer breaks. - **Security.** Hiding internals means consumers can't reach around the rules. The API is the chokepoint where authentication (who you are) and authorization (what you're allowed to do) get enforced. - **Reuse.** One service, many consumers. A shipping service exposed through an API can be called by the web app, the mobile app, and a partner's system, all at once. - **Parallel work.** Once the contract is agreed, the team building the consumer and the team building the service can work at the same time, against the spec, instead of one blocking the other. The "reuse" point is what made APIs ubiquitous. Modern software is largely a graph of services talking to each other through APIs — payment providers, auth providers, AI models, internal microservices. None of it works without that contract layer [2][3]. ## The contract has a shape An API isn't a vague promise; it declares specific operations, what they accept, and what they return. A typical entry in the contract looks like: ``` GET /orders/{id} path param: id (string) returns: { id, status, total, items[] } errors: 404 if not found, 401 if not authenticated ``` That's a single operation, fully specified. The consumer knows the verb (GET), the path, the input, the output shape, and the failure modes — without ever knowing whether /orders/{id} is backed by Postgres, a flat file, or a call to another API. The shape is the contract; the implementation behind it is the service's private business. A real API is a collection of these operation specs, plus the rules around them (authentication, rate limits, versioning). Designing an API well is mostly the discipline of choosing those operations, names, and shapes deliberately — which is what the rest of this series is about. ## How I use this The payoff is diagnostic and design-shaped. When something breaks between two services, I now ask first: *is this a contract violation or an implementation bug?* A consumer sending the wrong shape is a contract problem; a service returning the right shape with wrong data is an implementation problem — and the fix lives in a different place. When designing a new endpoint, the contract framing keeps me honest: I write down the operation, inputs, outputs, and errors *before* the code, because that's the part the consumer actually depends on. The implementation can change; the contract is what I'm promising. ## References [1] IBM, "What is an API?," 2024. [Online]. Available: [https://www.ibm.com/topics/api](https://www.ibm.com/topics/api) [2] Postman, "Getting Started with APIs," 2024. [Online]. Available: [https://www.postman.com/what-is-an-api/](https://www.postman.com/what-is-an-api/) [3] Amazon Web Services, "What is an API?," 2024. [Online]. Available: [https://aws.amazon.com/what-is/api/](https://aws.amazon.com/what-is/api/) ```quiz Q: An API is best described as… - the full source code of a service, shared with consumers - a deliberate, stable surface a service exposes so others can use it without knowing its internals correct: 1 explain: The interface is the carve-out. Consumers depend on the surface, not the implementation behind it. Q: Why does swapping a service's database not break its consumers? - because the API contract stays the same even when the implementation changes - because databases never affect API behavior correct: 0 explain: As long as the exposed surface (operations, inputs, outputs) keeps its contract, the internals can change freely. Q: Which of these is NOT a benefit of having a defined API surface? - security enforced at a single chokepoint - parallel work by consumer and service teams against a spec - consumers getting direct read/write access to the service's private tables correct: 2 explain: Hiding internals is the point. Letting consumers touch private tables is the opposite of an interface. Q: A contract entry for an operation should declare at minimum… - the verb/path, inputs, output shape, and error modes - only the URL correct: 0 explain: The consumer depends on the full shape — what to send, what comes back, and how failures look. ```