{"canonical_url":"https://engineer.company/glossary/api/","content_markdown":"# API\n\n## What it is\n\nAn API, short for application programming interface, is the published set of operations a\npiece of software offers to other software: what each operation is called, what it accepts,\nwhat it returns and how it reports trouble. The plural is APIs. The caller learns that surface\nand nothing behind it, so the program on the far side can be rewritten, moved to another\nmachine or split in three, and the caller keeps working as long as the surface holds.\n\nThe word covers several layers. A library's API is the functions and types it exports, called\ninside one process. An operating system's API is its set of system calls, and POSIX standardises\na common core of them so that a program written against `open` and `read` builds on more than\none Unix-like kernel. A web API is offered across a network, almost always over HTTP, and that\nis what most people mean by the bare word today: a server answering requests at addresses such\nas `/v1/orders`, usually with JSON in the body.\n\nWeb APIs come in a handful of styles. Resource-oriented ones, often called REST-style, give\neach thing an address and use HTTP's methods to read and change it. RPC-style ones, such as\ngRPC, publish named procedures with their arguments and results declared in advance. GraphQL\noffers one endpoint and a type system, and the client writes a query naming exactly the fields\nit wants back. Webhooks turn the direction round: the provider calls an address the customer\nregistered when something happens.\n\nThree neighbouring words get mixed up with it. A protocol, such as HTTP, defines how messages\ntravel; an API is what one particular service says in that protocol. An SDK is a library in one\nprogramming language that wraps someone's API, so a developer calls a function instead of\nassembling requests. And the implementation is the code behind the API, which a caller never\nneeds to read.\n\n## Why it matters\n\nAn API is the part of a system that other people build on, which makes it a promise that\noutlives the code behind it. Rewriting a handler takes an afternoon. Changing what that handler\nreturns can break an app already installed on customers' phones, a partner's nightly import\nor a script nobody remembers writing.\n\nSo the first decision is about audience. A private API, used only by the team's own frontend,\ncan change in the same pull request as its one client. A public API changes through\ndeprecation and notice, and every field it ships is a field to support for as long as anyone\nreads it.\n\nThe second decision is how strict the contract is. A strict API declares a type and a limit for\nevery input, rejects what it does not recognise and answers each failure with a precise status\ncode. It catches mistakes at the door and is easier to document, test and generate clients\nfor. A lenient API accepts whatever arrives and does its best, which feels friendly in the first\nmonth and then turns every accident of the implementation into behaviour somebody depends on.\nStrictness costs design time up front; leniency costs more later, at a moment nobody chooses.\n\nThe third decision concerns other people's APIs. A payment provider, a mapping service or a\nlanguage model is an API the product calls and does not control: prices move, versions are\nretired, quotas tighten. Calling a vendor directly from fifty places makes a switch a rewrite.\nCalling it from one module the team owns makes the switch a change to that module. The wrapper\ncosts a little indirection and buys a way out.\n\nSemantic Versioning gives this promise a vocabulary: the major number goes up when the public\nAPI changes in a way that is incompatible, so a client can tell from the version alone whether\nan upgrade is safe. Over HTTP there are several places to signal a break, and RFC 9205, the\nIETF's guidance for protocols built on HTTP, lists a new link relation, a new media type or a\nnew header field among them.\n\n## What it looks like in practice\n\nThe APIs behind several projects on this site were shaped by one question: what belongs in the\nAPI, and what belongs somewhere else.\n\nOn NextMariner, a maritime platform for professional networking, company reviews and sponsored\neducation, the founder's architecture contribution included\n[keeping the Go API deliberately thin](/portfolio/a-maritime-platform-built-in-clean-layers/).\nBuilt with Huma over Fiber, it routes, validates the request, applies the security filtering and\norchestrates, and holds no business logic at all. The rules live in PostgreSQL functions, so\na rule change happens in one layer, in SQL. The boundaries were written down and enforced in\nreview. That makes the API a boring adapter, in the good sense.\n\nA related project took the shaping out of the API as well.\n[PostgreSQL functions assemble each response as JSON](/portfolio/designed-a-json-passthrough-from-postgres-to-api/),\nand the Go handler receives it as `json.RawMessage` and forwards it untouched, through a small\n`QueryJSON` helper. The DTOs, mappers and response structs a layered API usually collects fell\naway, handlers got dramatically shorter, and the frontend no longer depended on Go.\nThe trade-off is worth naming: the shape of the API's responses is now defined in SQL, so\nthat is where a reviewer reads the contract.\n\nAn API that anyone can reach also has to defend itself. A public directory of companies and\nprofessionals sits behind\n[22 rate limiters, each built for the path it protects](/portfolio/built-fail-closed-rate-limiting-and-anti-abuse/),\nwith their state in Redis so a limit holds across instances. When Redis is unreachable the\nlimiters fail closed and refuse traffic. Cloudflare Turnstile, an origin lock, a bespoke\nchallenge on the directory and 351 lines of idempotency middleware, which stops a retried write\nlanding twice, complete the defences. The page states the cost plainly: a Redis problem becomes\na problem users can see, which was preferred to a Redis problem becoming a billing one.\n\n## Where it goes wrong\n\nAPI failures tend to arrive late, once the clients and the data have grown.\n\n**A renamed field breaks a client nobody knew about.** Once an API is published, someone\ndepends on every observable detail: field names, the order of a list, the wording of an error.\nRename `customer_name` to `name` and a partner's integration breaks on the next request. Change\nby addition instead: add the new field beside the old one, mark the old one deprecated, watch\nthe logs until nobody reads it, and remove it only in a new major version.\n\n**A list endpoint gets slower every month.** It returns every matching row, which was fine with\nfifty records at launch and times out at two hundred thousand. Paginate from the first release,\nwith a default page size and a hard maximum the client cannot exceed. For large or busy\ncollections prefer a cursor to an offset: with an offset, a row inserted between two requests\npushes another row onto the next page, where the client reads it twice.\n\n```http\nGET /v1/orders?limit=50\u0026after=ord_8f2c HTTP/1.1\nHost: api.example.com\n```\n\n**One customer reads another customer's order.** The API checks that the caller is signed in\nand then loads `/v1/orders/42` by its identifier alone, so changing the number in the address\nwalks through other people's data. Authentication answered who is calling; nothing asked\nwhether that caller owns order 42. Scope every lookup by owner inside the query itself, and\nkeep a test that signs in as one account and requests another account's records.\n\n**The response carries columns nobody meant to publish.** An endpoint serialises a database row\nor an ORM object as it stands, so a password hash, an internal flag or a supplier's cost price\ngoes out to every client, and a column added next year is published the day it is created. The\nsame mistake on input lets a request set `role` or `is_admin` by including it in the body.\nGive each endpoint explicit input and output types that list the fields allowed, so publishing\na field becomes a decision someone makes.\n\n## Further reading\n\n- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — the methods, status\n  codes and headers that every web API is built from, defined by the IETF.\n- [RFC 9205: Building Protocols with HTTP](https://www.rfc-editor.org/rfc/rfc9205) — best\n  current practice for designing an application on top of HTTP, including how to evolve it.\n- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457) — a\n  standard JSON shape for error responses, so clients parse every failure the same way.\n- [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585) — where 429\n  Too Many Requests and its `Retry-After` hint for rate-limited clients are defined.\n- [Semantic Versioning 2.0.0](https://semver.org/) — the rules for signalling an incompatible\n  API change through a version number.\n\n\u003chttps://engineer.company/glossary/api/\u003e\n","date_modified":"2026-11-08T02:22:23Z","description":"What an API is, why its shape outlives the code behind it, how to change one without breaking clients, and four mistakes that surface in production.","formats":{"gemtext":"https://engineer.company/glossary/api/index.gmi","gopher":"https://engineer.company/glossary/api/gophermap","html":"https://engineer.company/glossary/api/","json":"https://engineer.company/glossary/api/index.json","markdown":"https://engineer.company/glossary/api/index.md","pdf":"https://engineer.company/glossary/api/index.pdf"},"kind":"page","language":"en","title":"What is an API?","url":"https://engineer.company/glossary/api/","version":1}