The Information Architecture Philosophy Behind RESTful Web API Patterns and Practices Cookbook
These principles are not just about API design—they represent a philosophy of open, decentralized, and adaptive information systems.
The guiding principles outlined in my book RESTful Web APIs Patterns and Practices Cookbook emphasize global reach, adaptability, and long-term sustainability. The supporting principles of Discovery, Extension, Composition, Evolution, and Longevity reflect a direct information architecture philosophy rooted in decentralization, open-ended growth, and emergent complexity.
There are details in the book, even a dedicated appendix on the topic. I've also spoken about these principles in a number of talks in the last couple years. And I thought it would be helpful to post them here with some additional commentary on the thinking behind them and the impact adopting them can have on your API projects.
Discovery (Findability & Reusability)
This principle aligns with linked data, hypermedia, and affordance-based discoverability. The ability to find and use APIs dynamically without prior coordination echoes information retrieval and open knowledge networks. This is similar to the way search engines or semantic web technologies enable discovery of content across the web.
It also suggests a self-descriptive architecture, where APIs expose enough metadata and affordances to enable unknown consumers to find and use them.
Extension (Unanticipated Uses & Flexibility)
This principle embraces the generativity of APIs -- services should not be tightly constrained by preconceived use cases. Instead, they should provide affordances that enable unexpected applications.
Architecturally, this reflects an adaptive information system, similar to open-ended platforms (e.g., the Web itself, Unix pipes, or even biological ecosystems).
This concept is akin to Christopher Alexander’s pattern language, where components are designed to be reusable and combinable in unforeseen ways.
Composition (Interoperability & Loose Coupling)
Encourages modularity and emergent collaboration—where APIs, like self-organizing systems, allow unknown entities to safely interact.
This mirrors the stigmergic coordination seen in decentralized systems, where independent actors (users, services) can leverage affordances left by others to achieve higher-level functionality.
Reflects Douglas Engelbart’s idea of augmenting human intellect by enabling APIs to be building blocks for composable solutions.
Evolution (Resilience & Adaptation Over Time)
Recognizes that software and APIs are never static. They evolve as part of an information ecosystem.
This is an anti-fragile approach (Nassim Taleb) where APIs not only withstand change but benefit from it.
It aligns with Donella Meadows' systems thinking, where feedback loops allow adaptive, self-sustaining evolution.
Longevity (Sustainability & Adaptability)
Acknowledges that API systems must be designed for long-term change, not short-term rigidity.
Reflects Roy Fielding’s REST principles, which advocate for constraints that allow distributed systems to persist beyond individual implementations.
This is a non-deterministic approach to information architecture, where design is about enabling sustainable, evolving interactions rather than fixed structures.
Connecting to ALPS and Affordance-Driven Design
These principles deeply align with ALPS (Application-Level Profile Semantics) and the affordance-driven approach to API design that I developed more than ten years ago with the help of Leonard Richardson, Mark Foster, and a few others.
In particular:
Discovery aligns with self-descriptive, affordance-rich APIs.
Extension supports open affordance spaces where clients can interpret new actions dynamically.
Composition fits with hypermedia as a system of interwoven, reusable components.
Evolution and Longevity reinforce the importance of designing APIs as evolving ecosystems rather than static schemas.
Also …
These principles are not just about API design—they represent a philosophy of open, decentralized, and adaptive information systems. They reflect systems thinking, complex adaptive systems, and long-term digital sustainability. By embracing these ideas, API designers can move beyond rigid, brittle interfaces to create resilient, self-adapting, and user-driven API ecosystems.