Design
UX review presentations
How do you create compelling presentations that wow your colleagues and impress your managers?
20 Jan 2027 • 10 min read
Building your API stack
The rise of RESTful APIs has been met by a rise in tools for creating, testing and managing them.
Lana Steiner
Engineering Manager, Layers
An API stack is mostly a set of agreements: what a resource is called, what an error looks like, and who is allowed to change either. Tools help, but only after those agreements exist.
Introduction
Teams usually adopt tooling in the wrong order. They buy a gateway before they have a schema, and a schema before they have decided whether the API is a product or an implementation detail.
Answer that question first. A public API is versioned, documented and slow to change. An internal one can be none of those things, and pretending otherwise costs you a year of ceremony.
Once that is settled, the stack more or less falls out of it. A schema you generate from, a mock server your client team can develop against, and a contract test that fails the build when the two drift apart.
We stopped writing API documentation the day we started generating it. The documentation had been wrong for eight months and nobody had noticed.
Errors deserve as much design attention as the happy path. A consistent error shape — a stable code, a human message and a machine-readable field — removes more support tickets than any amount of endpoint tuning.
Pagination, filtering and sorting should look identical on every collection. Consumers learn the pattern once and stop reading your docs, which is the outcome you want.
Software and tools
Generate the client, do not hand-write it. Hand-written clients drift, and the drift is discovered by a customer rather than by a test.
Keep the gateway thin. Every piece of business logic that ends up in routing configuration is logic your tests cannot see and your engineers cannot grep for.
Other resources
Three decisions do most of the work when you are assembling a stack:
- Is this API a product with users, or an internal boundary?
- What breaks the build when the schema and the implementation disagree?
- Who is allowed to add a field, and who has to be told?
None of this requires a platform team. It requires one repository that owns the schema and one test that refuses to pass when reality disagrees with it.
Everything else in the stack is a convenience built on top of those two things.
Conclusion
Pick the agreements first and the tools second. Tools chosen before agreements simply encode the confusion you already had.
Generate what you can, test the contract, and keep the error shape identical everywhere.
Do that and the stack stops being a stack and starts being a boundary people trust.
Share this post
