Patterns for API Design
This article is the fifth and final part of our adoption story series. Throughout this journey, we’ve explored, discussed, and put to the test the design patterns from the excellent book Patterns for API Design. Our goal has been to see how these patterns hold up in the Dutch Energy Sector, helping us build APIs that are easy to use, high-performing, secure, and reliable – all while navigating some tricky design decisions along the way.
So far, we’ve shared four pattern stories about our progress: the first was published on March 26, 2023, the second on August 26, 2023, the third on January 26, 2024, and the fourth on March 27, 2025.
Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges by Olaf Zimmermann and co-authors Mirko Stocker, Daniel Luebke , Uwe Zdun , and Cesare Pautasso (published November 2022) is our go-to guide for designing better APIs. It’s packed with practical ideas and patterns that have really inspired and helped us in our own API design work.
Patterns for API Design is a catalog of 44 design patterns. This final pattern story presents feedback and review comments on the remaining 11 patterns:
- Frontend Integration: a pattern responsible for displaying and controlling the end-user interface, typically physically separated from the backend
- Backend Integration: a pattern enabling physically separated backend systems to exchange data and trigger actions via message‑based APIs
- Community API: a pattern where an API is exposed only to a restricted group of users across multiple organizations, with access controlled by deploying it in an access-restricted location
- Solution-Internal API: an internally scoped API used only by components or services within the same application or logical tier
- State Creation Operation: a pattern where an API endpoint allows clients to create new state or trigger events by sending write-only requests, without requiring immediate processing or response beyond acknowledgment
- Computation Function: a side‑effect‑free API operation that calculates a result solely from client‑provided input, without reading or modifying any server‑side state
- Operational Data Holder: a pattern where an API exposes endpoints to create, read, update, and delete frequently changing, short-lived business data with many outgoing relationships
- Master Data Holder: a pattern where an API provides access to long-lived, rarely changing master data that is referenced by many clients
- Reference Data Holder: a pattern where an API provides read-only access to static, rarely changing data—like country codes or units of measurement—that is referenced throughout a system but remains immutable for clients
- Link Lookup Resource: a pattern where an API endpoint provides clients with the current addresses of other API endpoints, enabling dynamic discovery and reducing direct address coupling between services
- Wish Template: a pattern where clients specify a hierarchical template in their request to indicate exactly which nested data elements they want included in the API response
Our practitioner community’s feedback includes real-world examples of how concepts are used (Known Uses), input from ongoing discussions, key takeaways, and ideas for adopting these concepts. The fifth adoption story is available on the Patterns for API Design website:
Pattern Adoption Stories from Readers: Dutch Government & Energy Sector (5/5)
In this final pattern story, we’ll discuss the ‘less is more’ principle, explore why these patterns matter in the world of AI, LLMs, and MCP, and let the book speak for itself with some of our favorite lines. Enjoy, and let us know what you think!
Datensparsamkeit
The term Datensparsamkeit comes from Germany and is deeply embedded in German data protection law and culture. It combines the words Daten (data) and Sparsamkeit (frugality or thrift), and can be roughly translated as ‘data minimization’, ‘data parsimony’, or even ‘minimalistic-data-minded‘ – with an emphasis on mindset or attitude.
Martin Fowler uses Datensparsamkeit to describe a mindset around data collection that’s all about keeping things to the bare minimum. The idea is to always ask: ‘do we really need this data?’ and to avoid collecting or storing more than what’s truly necessary. It’s a simple but powerful principle and one that lines up well with what the GDPR later made official.
The term is difficult to translate precisely, which brings to mind an old saying:
Traduire, c’est trahir (French: “To translate is to betray”)
Such proverbs remind us that the exact meaning of some concepts is often lost in translation – Datensparsamkeit being a perfect example. That’s why we’ve conformistically adopted Datensparsamkeit as a loanword in our sector, no Anticorruption Layer 🙂 needed!
Numerous approaches can help streamline messaging and minimize unnecessary data transfer in API and message design, striving for Datensparsamkeit. Five API design patterns from the book that support this goal are Pagination, Wish List, Wish Template, Conditional Request and Request Bundle:
Datensparsamkeit design patterns
These five data transfer parsimony patterns are explained in detail in this excerpt, which further discusses how to shape API responses effectively and avoid unnecessary data transfer.
Less is more
The key principle of API design is simple: less is more. This applies not only to functionality and structure, but especially to the data an API exposes. The concept of Datensparsamkeit reminds us to share only what’s truly necessary. In API design, Datensparsamkeit and the ‘Less is More’ principle converge on the same best practices.
Simplicity brings focus. APIs that try to serve everyone risk feature creep, becoming bloated and difficult to use. What may start as a well-intentioned goal can quickly lead to an API that tries to do everything, but ultimately does nothing well. Good API design is a balancing act: adding new features is easy, but removing them later is difficult and disruptive. That’s why minimizing conceptual weight is more important than simply reducing the number of classes or methods. Focused, lightweight APIs are easier to understand, maintain, and evolve.
Avoid creating a ‘big ball of method mud’ – focus on a specific target audience and their information needs:
If in doubt, leave it out
(This is one of the general rules stated in the book and one of our favorite quotes. You’ll find more memorable quotes at the end of this article).
AX and LLM
AI is already changing the API world, with smart agents quickly becoming the main users of APIs. This shift means we need to rethink how we design APIs – not just for developers (DX), but also for agent experience (AX). While DX is all about making things clear, consistent, and easy for human developers, AX focuses on helping AI agents (like LLMs) understand APIs, interact smoothly, and handle errors correctly.
Picture source: https://www.linkedin.com/pulse/navigating-api-jungle-taming-ai-driven-onslaught-style-rajat-singhal-r7eef/
Here are a few insights we’ve gathered that can help create a great agent experience (AX). In this quick overview, we highlight how many API design patterns from the Patterns for API Design book are still relevant and useful for this purpose:
- Apply a conservative ‘less is more’ approach to overall API design to promote simplicity and reduce the risk of AI hallucinations
- Provide ‘response-shaping’ functionalities to support ‘Datensparsamkeit’ – see the Data Transfer Parsimony patterns: Pagination, Wish List, Wish Template, Conditional Request and Request Bundle
- Consider GraphQL as a model for the MCP, thanks to its self-documenting introspection, response shaping capabilities, and ability to aggregate multiple resources in a single query. The Wish List and Wish Template patterns are abstractions inspired by GraphQL’s approach
- Avoid deeply nested objects – apply an Atomic Parameter List instead of Parameter Trees and Forests (otherwise it’s hard for AI to see the forest for the trees 😊)
- API Description: make your documentation explicit to prevent implicit assumptions (sounds like Hyrum’s Law 😊). In fact, we need better documentation more than ever!
- Error Report: use RFC 9457’s custom-fields (extension) mechanism for more detailed error handling; this helps the LLM or agent fix errors (bonus: improves DX!)
- Use enums whenever possible don’t leave it up to the AI to guess what a value should be (again: reduces chances of ‘hallucination’) – Atomic Parameter (List)
- Standardized and well-known accessibility and easy onboarding: OIDC and OAuth for authentication and authorization – Public API, API Key, Context Representation
The design patterns in Patterns for API Design are abstract and timeless, making them valuable and highly applicable for building robust and secure APIs in the new AI era as well.
When it come to AI-friendly API design – we really enjoyed the ‘AI Agents are Coming for Your API – Are You Ready?’ video by Zdenek Nemec and Emmanuel Paraskakis. We believe it is essential viewing for API designers, engineers, and architects who want to polish their surfboard to surf the AI wave🏄.
Favorite lines
As we wrap up this series on adoption stories, we want to finish by sharing some of our favorite quotes and passages from Patterns for API Design. It feels right to let the book speak for itself one last time. We might be repeating ourselves a bit, but we hope this final post encourages other API architects, designers, and developers to check out Patterns for API Design. Honestly, we think this book is a must-read for anyone involved in modern system design. If you want to make a real impact in system design, you should definitely get to know the API design ideas and patterns it covers.
