API design
Planted Aug 2020 Tended 3 years ago Linked from 4 notes
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)