Patterns for API Design: Adoption Story Part 4

Patterns for API Design

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, 33 patterns from the book have been studied and reviewed. This fourth pattern story covers the following twelve patterns:

  • 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
  • Parameter Tree: defines a hierarchical structure of an Atomic Parameter, List, or another Tree
  • Parameter Forest: combines multiple Parameter Trees in the request or response payload of an API operation
  • Data Element: a message-level pattern typically used in requests and responses, such as payload attributes
  • Aggressive Obsolescence: aimed at decommissioning entire APIs or outdated components
  • 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
  • Pricing Plan: enables API providers to define and attach usage-based billing schemes to the API description
  • Request Bundle: groups multiple requests into a single message container to minimize the number of network calls and optimize data‐transfer efficiency
  • Semantic Versioning: describes different levels of change using a hierarchical three-number versioning scheme

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!

The practitioner community’s feedback consists of Known Uses and Discussion Input. The fourth adoption story is available on the Patterns for API Design website:

Pattern Adoption Stories from Readers: Dutch Government & Energy Sector (4/4)

In this article, we also explore the complex, ‘wicked’ challenges of API design and general design practice. 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 on api-patterns.org and in the book Patterns for API Design, API design is described as a ‘wicked problem’ – one that has no single, definitive solution, where solving one issue often uncovers new ones, and only partial resolutions are possible.

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:

    1. DX (Developer Experience): APIs should deliver a positive developer experience through clarity, stability, ease of use, and functionality
    2. OX (Operator Experience): From an operational standpoint, APIs must be reliable, high-performing, secure, and easy to manage at runtime
    3. MX (Maintainer Experience): From a management perspective (MX), APIs need to be maintainable, evolvable, and backward compatible, balancing agility with stability

    Building on DX, OX, and MX there is also Value Exchange (VX) – a concept Erik Wilde introduced to tie it all together: an API only survives long term if what it delivers to consumers offsets the cost of building and running it – whether that’s direct revenue, cost savings, or even broader benefits like improving public services. You could even say that without a balanced Value Exchange (VX), a (public) API wouldn’t be viable. Even the best UX and DX won’t sustain an API unless its provider gains enough benefit to justify keeping it running.

    A new kid on the block is AX (Agent Experience). AX is all about making sure APIs work just as well for the growing crowd of AI agents as they do for people. As more workflows become automated and agents start handling tasks independently, it’s important to design APIs that these agents can understand and use smoothly. Putting AX on the same level as DX (Developer Experience), OX (Operator Experience), MX (Machine Experience), and VX (Value Exchange) is key to making your APIs future-ready. AI agents are joining the party, and it’s time to treat them like first-class users in our digital workflows.

    Ultimately, great APIs come from striking the perfect balance between technical rigor, usability, and that ‘it just feels right’ vibe. We often talk about ‘usability’ and ‘intuitive design’ as if they’re abstract – but really it’s just the sum of every little interaction a developer has with your API and your team. Since developers are the ‘users’ of an API product, DX really is a slice of UX.

    Alongside Developer Experience (DX), it’s essential to consider an API’s usefulness (UX) and its long-term sustainability (VX), and now Agent Experience (AX). If we neglect these dimensions, we risk pouring all our effort into DX and missing the broader strategic picture. At its core, great DX shares many of the same guiding principles as UX. In the next section, we’ll examine the key elements of UX more closely.

    The Design of Everyday Things

    Don Norman’s The Design of Everyday Things provides foundational concepts for User Experience (UX) that can be applied to API design. Norman introduced ‘user experience’ in the first edition of his book, arguing 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: 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 Patterns

    • Signifiers: The API Description pattern serves as a signifier, indicating where and how to interact with the API through examples and explanations
    • Constraints: Public API, Community API, Solution-Internal API patterns establish boundaries on who can access the API, constraining its use to appropriate audiences
    • Conceptual model: Frontend and Backend Integration 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 Patterns

    Structure Patterns

    • Signifiers: Element Stereotypes patterns signal where and how to act
    • Mapping: Representation Elements patterns organize and structure data and establish a clear mapping between the conceptual model and its concrete representation
    • Feedback: The Error Report pattern is a special-purpose representation that provides meaningful error messages
    • Constrains: Structure patterns define limitations on what data can be included in requests and responses

    Quality Patterns

    Evolution Patterns

    • Signifiers: The Version identifier pattern serves as a signifier indicating where and how to interact with the API endpoints
    • Constraints: Evolution patterns establish limitations on changes to maintain backward compatibility and lifetime gaurantee
    • 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 Reading

      Other recommended resources that draw on Don Norman’s The Design of Everyday Things to inform API design include:

      • Erik Wilde’s LinkedIn post: Is API Developer Experience (DX) Overrated? What’s more important than DX? (Highly recommended!)
      • Lynn Roots’ article that parallels physical affordances and signifiers with API endpoints, methods, and naming conventions;
      • Arnaud Lauret’s (The API Handyman) youtube vid that acknowledges how Norman’s book reshaped his approach to API usability and consistency
      • Xavier Spriet’s article on the confluence of of UX and DX for API Design

      Originally published on: https://www.linkedin.com/pulse/patterns-api-design-adoption-story-part-4-ton-donker/

      Scroll to Top