This article is the fourth part in a series of adoption stories in which we explore, discuss, and, in some cases, apply the design patterns from Patterns for API Design. Our challenge has been to put these patterns into practice within the energy sector, with the goal of designing APIs that are easy to use, easy to understand, and both secure and reliable – all while navigating the necessary design decisions and trade-offs along the way.
So far, this journey has resulted in three previously published adoption stories: the first released on March 26, 2023, the second on August 26, 2023, and the third on January 26, 2024.
“Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges” is a book co-authored by Olaf Zimmermann, Mirko Stocker, Daniel Lübke, Uwe Zdun, and Cesare Pautasso, published in November 2022. It serves as the Swiss army knife for software engineers and architects in designing, evolving, and documenting APIs. We regard this book as an outstanding resource — one that has inspired us and strengthened our belief that its architectural insights and patterns can deliver meaningful value in our API design work.
At the time of this writing, 31 patterns from the book have been studied and reviewed. This fourth adoption story focuses on the following patterns:
- Aggressive Obsolescence: aimed at decommissioning entire APIs or outdated components
- Atomic Parameter: a fundamental pattern that defines simple and unstructured data to be exchanged between client and provider
- Atomic Parameter List: groups multiple related Atomic Parameters into a descriptive representation element
- Data Element: a message-level pattern typically used in requests and responses, such as payload attributes
- Experimental Preview: provides beta versions of an API to showcase interim developments to (future) customers
- Limited Lifetime Guarantee: informs consumers about the expected duration of an API’s availability and reliability
- Link Element: references endpoints and operations within request and response message payloads
- Parameter Forest: combines multiple Parameter Trees in the request or response payload of an API operation
- Parameter Tree: defines a hierarchical structure of an Atomic Parameter, List, or another Tree
- Semantic Versioning: describes different levels of change using a hierarchical three-number versioning scheme
The practitioner community’s feedback consists of Known Uses and Discussion Input, and the four integrated adoption stories can be found here:
https://api-patterns.org/book/pattern-adoption-story-1
In this article, we also explore the tough, “wicked” challenges of API and general design. What truly makes a design “good,” and how can we craft APIs that feel natural and intuitive for developers? Enjoy the read, and please share your thoughts in the comments!
Wicked problem
Both api-patterns.org and the Patterns for API Design book describe API design as a “wicked problem” – one that has no single, definitive solution, where solving one issue often uncovers new ones, and only partial resolutions exist.
A wicked problem is a complex issue with no single, clear-cut solution; addressing one aspect often creates new challenges, and the problem can only be partially resolved in multiple ways
API design is a wicked problem because it sits at the intersection of technical requirements and human factors. As outlined in the Patterns for API Design book, API design presents unique complexities due to its impact on developer experience (DX), performance, scalability, reliability, and security. Key nontechnical challenges include balancing diverse client needs, market competition, unreliable networks, data exposure risks, backward compatibility during evolution, mismatched client-backend expectations, and rapid technological shifts. Taken together, these factors make API design an ongoing balancing act rather than a one-and-done project – requiring continuous feedback, collaboration, and evolution.
The many challenges of API design
The book also identifies the need for Operator Experience (OX) and Maintainer Experience (MX), alongside Developer Experience (DX), leading to the following key stakeholder perspectives:
- DX (Developer Experience): APIs should deliver a positive developer experience through clarity, stability, ease of use, and functionality
- OX (Operator Experience): From an operational standpoint, APIs must be reliable, high-performing, secure, and easy to manage at runtime
- MX (Maintainer Experience): From a management perspective (MX), APIs need to be maintainable, evolvable, and backward compatible, balancing agility with stability
Success comes from designing APIs that developers genuinely enjoy using – striking the right balance between technical precision, usability, and intuitive design. But what do we really mean by “usability” and “intuitive understanding”? Great developer experience (DX) is built on three layers: functionality (what the API does), usability (how easy it is to use), and the overall experience (how it feels to use). That last layer—how the developer feels—might sound abstract, but it’s really just the sum of every interaction between the developer and the API provider. For API products, developers act as the end users—making developer experience effectively a subset of user experience. In many scenarios, APIs serve as the primary interface to a service, with developers as the end users. In this sense, APIs are the interface, and the user experience (UX) is found in the ease-of use of these APIs.
So, does great DX start with the same principles as UX? In many ways, yes. Let’s take a closer look at the different aspects of UX in the next section.
The Design of Everyday Things
The Design of Everyday Things by Don Norman is a foundational book on User Experience (UX). It explores how good design makes everyday objects intuitive and easy to use, emphasizing the importance of understanding human behavior. Norman introduced “user experience” in the first edition of The Design of Everyday Things (originally titled The Psychology of Everyday Things). He argued that design must account for affective, behavioral, and contextual factors, not just interface mechanics.
You might have heard of the Norman’s Doors metaphor. It refers to doors so badly designed that you can’t tell whether to push or pull them.
picture source: (2) Explaining UX Design 101 with (Norman) Doors! | LinkedIn
The idea highlights how poor design makes people stop and think about something that should be obvious. In software (like APIs), it’s a reminder that good design should feel natural and intuitive — users should instinctively know how to use it without extra effort or confusion.
Just as Norman’s principles demand user-friendly physical interfaces, effective API design requires prioritizing developers’ needs through intuitive endpoints, clear documentation, and error handling that guides rather than frustrates. The “best” APIs, like well-designed everyday objects, empower users seamlessly—blending technical rigor with the human touch. So what defines ‘good design’?:
Two of the most important characteristics of good design are discoverability and understanding. – Don Norman, The Design of Everyday Things
Let’s take a closer look at discoverability and understanding.
Discoverability
Discoverability is about whether users can figure out what actions are possible and how to perform them. Don Norman breaks this down into five key elements:
- Affordances define what actions are possible based on the relationship between the user and the object (e.g., a door handle affords pulling if you can reach it).
- Signifiers are cues that highlight affordances, like a “push” label on a door.
- Constraints limit available actions, guiding user behavior through physical, logical, or cultural boundaries (e.g., a puzzle piece only fits in one spot).
- Mapping refers to the intuitive relationship between controls and their effects—like switches aligned with the lights they control.
- Feedback provides users with clear, timely responses to their actions. Too much can overwhelm, too little can confuse.
Together, these elements influence how easily users can make sense of and interact with a system. The five key aspects of discoverability—affordances, signifiers, constraints, mappings, and feedback—also form the foundation of the second pillar of good design: understanding.
Understanding
Understanding is about how easily users can figure out how a product works. Key element here is:
- Conceptual model—a simplified mental representation of how a system or product works.
Designers have their own mental model when creating a product, but developers often form a different one. Since designers can’t directly explain their thinking, the product itself must communicate how it works. Clear, consistent communication – through affordances, signifiers, constraints, mappings, and feedback – helps developers build accurate mental models and makes the product more intuitive and enjoyable to use.
Mapping UX Principles to API Design Patterns
Now, let’s apply Norman’s core concepts to API design by mapping his human-centered principles – affordances, signifiers, constraints, mapping, feedback, and conceptual models – onto the API design patterns and it’s categories presented in the book. Here’s what a possible mapping outcome might look like (open for interpretation and is not presented as an absolute truth):
The above mapping can be explained and motivated as follows:
- Foundation signifiers – In particular, the API Description pattern serves as a signifier, indicating where and how to interact with the API through examples and explanations
- Foundation constraints – Public API, Community API, Solution-Internal API: these patterns establish boundaries on who can access the API, constraining its use to appropriate audiences
- Foundation conceptual models – Frontend and Backend Integration: these patterns help shape understanding of how the API fits into the larger ecosystem and the API description pattern helps developers form accurate mental models of the API’s purpose and behavior
- Responsibility affordances – Operation Responsibilities patterns define and clarify the possible actions
- Responsibility mapping – Processing Resource: this pattern establishes the relationship between API operations and business processes
- Responsibilty conceptual models – Endpoint Roles patterns help build the user’s mental model of the API
- Structure signifier – Element Stereotypes Patterns that signal where and how to act
- Structure mapping – Representation Elements Patterns that organize and structure data
- Structure feedback – The Error Report pattern is a special-purpose representation that provides meaningful error messages
- Structure constrains – Structure patterns define limitations on what data can be included in requests and responses
- Quality feedback – Data Transfer Parsimony patterns ensure APIs provide appropriate feedback
- Quality constrains – Quality Management and Governance patterns: they establish limitations that maintain quality, such as Rate Limiting or Pricing Plan
- Evolution signifier -The Version identifier pattern serves as a signifier indicating where and how to interact with the API endpoints
- Evolution constraints – Evolution patterns establish limitations on changes to maintain backward compatibility and lifetime gaurantee
- Evolution feedback – Evolution patterns provide mechanisms for communicating changes and deprecations to clients
The above mapping exercise demonstrates that there is a clear connection between Don Norman’s The Design of Everyday Things and the catalog of design patterns provided by Patterns for API Design: by incorporating discoverability, feedback, clear conceptual models, intuitive affordances, effective signifiers, natural mappings, and appropriate constraints, API designers can create interfaces that are both easy to use and easy to understand. Applying the patterns from Patterns for API Design in the context of Norman’s human-centered design principles will lead to API designs that are more predictable, easier to understand, and more intuitive.
Design of Everyday APIs
By merging the why of Don Norman’s The Design of Everyday Things – which articulates the psychology behind intuitive design – with the how-to of Patterns for API Design, teams can engineer Developer Experiences (DX) that inherently elevate end-user application experiences (UX). Leveraging these time-tested guidelines ensures that APIs not only function correctly but are also intuitive, reliable, and scalable over time. The synergy between Norman’s UX principles and the Patterns for API Design framework results in APIs that are both technically sound and intuitively usable. API designers and product owners who value qualities such as usability and intuitive understandability should recognize Norman’s design principles and consider applying them to API design, making APIs feel as natural and effortless as well-designed everyday objects.
Recommend readings
Other recommended resources that draw on Don Norman’s The Design of Everyday Things to inform API design include:
- Lynn Roots article that parallels physical affordances and signifiers with API endpoints, methods, and naming conventions;
- Arnaud Lauret (The API Handyman) youtube vid that acknowledges how Norman’s book reshaped his approach to API usability and consistency
- Xavier Spriet article on the confluence of of UX and DX for API Design
- Erik Wilde’s LinkedIn post: Is API Developer Experience (DX) Overrated? What’s more important than DX?