engineering excellence
…addressing [[technical debt]] at the right time - adhering to good [[API design]] - keeping it going through [durable excellence](https://lethain.com/durably…
Contents
Arnaud Lauret’s Three Principles
An API is first and foremost an interface for people.
- Purpose: great APIs are mindful of what developers need from them. They hide away the implementation details consumers truly don’t need to care about, without imposing
- Usability: usable APIs are predictable: consistent (with itself, your organization, and existing standards), adaptable, and discoverable
- Constraints: be honest with your limitations. If you can’t handle infinite requests, impose (and document!) a rate limit. If you can’t handle requests for infinite data, impose (and document!) consistent pagination.
From https://nordicapis.com/the-three-principles-of-excellent-api-design/
A Philosophy of Software Design
John Ousterhout in A Philosophy of Software Design posits that abstractions should be narrow but deep: they expose as much functionality as possible via the most minimal interface.
Further Reading
- APIs as Ladders
- Tip: Group Like Properties (the example is for a JSON API but can apply to any property-based interface)
Mentions
-
-
Cognitive load
…I plan to write more on how this relates to [[API design]]. ## Further Learning - [Monoliths vs Microservices is Missing the Point—Start…
-
software architecture
…design) in scope rather than kind: while the programmer or [[API design|API designer]] may be concerned with putting functions and arguments…
-
Code reviews
…he calls "The Code Review Pyramid". For example, feedback on [[API design]] is more fundamental than feedback on style. Reviewers should spend…