Collaborative Design
This is a continued blog post series. You can find the first post here.
A Collaborative design process saves time
A Collaborative design process where customers, consuming developers and more people are involved speeds up the delivery time since we get feed back sooner. Compare this with a process where the API is build by backend developers, then the UI or app team starts to consume it. Then the app is released, and then first customer feedback is received.
The claim here is that the release cycle can be reduced, when upfront collaborative design is included.
Anti Patterns
Leaky abstraction anti pattern
If you omit the collaborative design process and goes for a code first implementation, then there is a tendency for technical things to leak in to the API contract. The book gives an example of a Lucene specific configuration file format that gets exposed in the API. The API consumer must upload a Lucene configuration file, which is clearly a leaky abstraction.
The Next Release Design Fix Antipattern
Without an API design process teams often find that late changes requires a new version. Since it would be to much work to fix the problem in the version about to getting released now.
It's difficult to get things exactly right the first time. Users often don't realize what they want until they se an example of what they don't want. This is taken from Jeff Patton's book 'User Story Mapping'. For many teams it becomes a big thing to get to talk to other teams or customers. We think we can guess what the right API contract is, and fall into the comfort zone of just working with in the team. This also feels more productive, since we can crank out more code. But often this means later rework, that could have been avoided by having a conversation with the right stakeholders upfront.
Big design up front is dumb but doing no design up front is even dumber.
The Heroic Design Effort Antipattern
With no upfront collaborative design effort, teams often need to resolve to heroic last minute changes to the API. Late in the process a design flaw or a missing functionality are revealed, leading to the heroic last minute design effort. An established process cannot guarantee perfect design, but has greater chances of avoiding these last minute changes.
The Unused API Antipattern
An API designed in isolation, often don’t get used at all. Since we failed to validate what the users actually needed.
The 5 Collaborative API Design-First phases
In the rapid API design-first approach 5 phases are presented.
- Discover: Determine the digital capabilities the API needs to deliver, searching for APIs that may already exist to meet the requirements.
- Design: Produce an initial API design or improve an existing API design to address the digital capabilities required but not available.
- Prototype: Produce a prototype or mock API to gain feedback from stakeholders regarding the current design. Revisit previous steps based on the feedback.
- Deliver: Deliver the API through a parallelized effort across developers, quality assurance, operations, and documentation teams. API capabilities are released iteratively rather than through a single release, driven by the agreed-upon API design.
- Onboard: Ensure customers, partners, and/or internal developers are onboard with the API, integrating it with their solutions. Support is critical at this stage to help teams with complex integration needs.
Collaborative Design is an Agile way of doing things.
7 principles from the agile manifesto gets re iterated.
- Our highest priority should be to satisfy the customer.
- We should welcome changing requirements, even late in development.
- We must strive to deliver working software frequently.
- Business people and developers must work together daily.
- Working software is the primary measure of progress.
- Be attentive to technical excellence and good design, as this enhances agility.
- Seek the simple by maximizing the amount of work not done.
The ADDR process
- Align: Ensures alignment of understanding and scope across business, product, and technology around a set of desired outcomes
- Define: Maps business and customer requirements into digital capabilities that will form the basis of one or more APIs to deliver the desired outcomes
- Design: Applies specific design steps for each API to meet the desired outcomes using one or more API styles
- Refine: Refines the API design through feedback from developers, in addition to documentation, prototyping, and testing efforts
7 Steps are used to go through the phases.
- Identify digital capabilities: Identify the customer needs and desired outcomes, including the corresponding digital capabilities that are required.
- Capture activity steps: Expand the digital capabilities to include a unified understanding and clarity through collaborative API design sessions.
- Identify API boundaries: Group the digital capabilities into API boundaries and determine whether the APIs already exist or new APIs are required.
- Model API profiles: Use a collaborative API modeling session to define the high-level API design, including resources and operations into an API profile.
- High-level API designs: Select one or more API styles that each API profile will offer and document the high-level design elements.
- Refine the design: Incorporate design feedback from API consumers using techniques that encourage improvement in the developer experience.
- Document the API: Complete the API documentation, including reference documentation and getting started guides, to accelerate integration.
The role of Domain Driven Design in API Design
James Higginbotham re-iterates the importance of taking the effort to consider the business perspective of an API effort. We should understand the business strategy, We should understand user needs and know their concrete problems and the outcomes we want to achieve when the API is released. Also remember the developer perspective.
Domain Driven Design is very much about business Capabilities and sub domains. The developers implementing the API need to understand these Capabilities and domains. They need to understand the language used by domain experts. This goes hand in hand with the agile principle of “Business people and developers must work together daily”.
If You ignore these things you will not end up with an API of great quality.
My comments
The first two chapters has introduced several lists of principles, phases, steps etc.
So I asked my self how do these relate to one another?
Lets try to illustrate that:
From chapter 1 we learned about the 3 API Design Elements, 3 API communication levels and 5 Web APi Design Principles.
Business Capabilities, product thinking, developer experience are the 3 API design elements that describes concepts that a great API must include.
The 3 communication levels describe the reality of an API that we must keep in mind to design a great API.
The 5 Principles gained through experience acts a heuristics to follow when designing an API.
.The concepts from chapter 1 are things we should keep in mind and all ways use as guiding principles.
The proposed way forward is to follow an API design-first approach or process which are described by 5 phases.
The 4 ADDR phases on the other hand are completed by following the 7 ADDR steps.
The combined ADDR phases and steps guides us through the API Design-first process, specifically by helping us identifying business requirements and convert them into an API Design.
So the concepts from chapter 2 are more concrete guidance steps to follow to obtain and fulfill concepts introduced in chapter 1.
Summary
Following an API design-first approach will give you an out side in perspective, that starts with customers, users, the business and the developers who is going to use the API. This will save you time in the long run. The ADDR process aims to help organizations to scale and streamline their API development efforts.
