Link:Sean Goedecke
Core Principles for Good API Design
Sean Goedecke outlines practical principles for API design, arguing that good APIs are boring, must never break existing consumers, and should favour developer ease over theoretical purity.
Principles of Good API Design: Familiarity, Stability, and Versioning
X postSarim MalikResource
Sarim Malik shares an essay by Sean Goedecke detailing practical API design. Effective APIs should be familiar and 'boring' rather than adhering to rigid REST or HATEOAS dogmas, with backwards compatibility taking top priority.
Key points
- Good APIs are boring: they should feel intuitive enough for developers to use them with minimal documentation overhead.
- The 'we do not break userspace' rule strictly prohibits breaking changes: additive fields are acceptable, but renaming or restructuring existing properties breaks downstream clients.
- API versioning (via URL paths like /v1/ or HTTP headers) is a necessary evil that introduces significant long-term maintenance and testing complexity.
- In the thread discussions, Malik highlights cursor-based pagination as his default choice due to its reliability and speed.
Why it matters
Published APIs are exceptionally difficult to change without disrupting integrations. Prioritising stability and familiar conventions from day one protects downstream consumers and reduces migration overhead.
Analysis
The piece advocates for engineering pragmatism over architectural purism. Because breaking changes erode developer trust and introduce severe downstream failures, consistency and predictability outweigh cosmetic interface improvements. The critique of API versioning highlights the trade-off between modernising interfaces and the compounding burden of supporting legacy endpoints.
Original post
Sarim Malik
@sarimrmalik · 14 August 2026
On good API design t.co/jMZpaa4Jkq
2.6k likes10 replies4.1k bookmarks194.9k views
View on XMore posts in the thread (2)
- @eduqr17 it's my default for pagination, so much more reliable + fast
- @lorenforeal Any specific resource you really like from the Google docs?
Selected replies (5)
- @lorenforeal @sarimrmalik This is solid advice, I usually point engineers to AIP by Google as the best starting place for an api standard. Even if you choose not to follow some of the things there is an excellent way to understand design of a consistent and reliable api
- @renideas @sarimrmalik Thanks I will have my agent read it
- @li9292 @sarimrmalik very insightful
- @eduqr17 @sarimrmalik i didn't know about cursor-based pagination, really cool!
- @veerbal01 @sarimrmalik Bookmarking to read it later
Mentioned links
Links and tools from this entry
Summary generated by AI (Gemini 3.8 Flash, 27 September 2026). It may contain errors – the original source is authoritative.
Related entries
Similar in content, found by the AI search.
X post:Adham Dannaway
Design Token Naming Guide by Adham Dannaway
Adham Dannaway has shared a dedicated guide on naming design tokens, aimed at helping teams establish structured token naming conventions and build design token systems.
305bookmarks12.6kviews
X post:Vinny
Three Design Principles for Coding Agents: Ditching Separate Memory Systems
Vinny highlights a post by Vox detailing three design principles from the creators of the coding agent Pi. Their main argument is that code is the definitive ground truth, making separate memory systems redundant. Furthermore, standard Bash tooling often beats complex protocols like MCP, and tool outputs should be loaded into context only when strictly necessary.
546bookmarks74.1kviews
Link:Jakub Krehel
Make Interfaces Feel Better: Design Engineering Principles for Polished UIs
Jakub Krehel shares 'make-interfaces-feel-better', a design engineering skill and guideline package for building and reviewing UI details. It covers rules across typography, surfaces, animations, icons, and performance, alongside a structured review methodology.
X post:jem
Alchemy: Introduction to Domain-Driven Design and Event Sourcing
A post by jem highlights the alpha release of Alchemy by Sam Goodwin. The linked guide explains core concepts of Domain-Driven Design (DDD), Event Sourcing, and CQRS using a banking example implemented in TypeScript.
228bookmarks7.1kviews
Link:Lev Selector
Simplicity in Software Development: Why Pragmatic Solutions Beat Over-Architecture
An essay arguing for radical simplicity in software design, showing that complex architectures and perfectionism often collapse under changing requirements, whereas simple, adaptable systems succeed.
Let's talk about your project
Locations
- Mattersburg
Johann Nepomuk Bergerstraße 7/2/14
7210 Mattersburg, Austria - Vienna
Ungargasse 64-66/3/404
1030 Wien, Austria
Parts of this content were created with the assistance of AI.