APIs are a conversation that involves everyone, from developers to end-users and even machine-to-machine. Yet, we can miss the mark when designing an API that delivers on the desired outcomes of the end user. In this talk, James discusses the factors that ensure an API delivers value to the end user. He will explore some techniques on refining your API design before it goes live. He will also explore the challenges of microservices and why they may not be what you think they are. Along the way, we will discuss techniques that can accelerate the API design and delivery process.
(Genuine) Escort Service Lucknow | Starting ₹,5K To @25k with A/C 🧑🏽❤️🧑🏻 89...
Refining Your API Design - Architecture and Modeling Learning Event
1. Refining Your API:
The Last Mile of API Design
James Higginbotham
@launchany
Photo by Francisco Fernandes on Unsplash
2. 2
@launchany
Introduction
• Consultant: API Strategy and Program Execution
• Speaker, Trainer, Author based in Colorado Springs, CO
• Author, “Principles of Web API Design: Delivering Value with APIs and
Microservices”
4. 4
@launchany
APIs are a Conversation: Machine-to-Machine
GET /projects
Accept: application/json
POST /projects
{ "projectName":"My Project", … }
GET /projects/12345
Accept: application/json
200 OK
Content-Type: application/json
[ { "projectId":"12344", … }, … ]
201 Created
Content-Type: application/json
Location: /projects/12345
200 OK
Content-Type: application/json
[ { "projectId":"12345", … }, … ]
5. 5
@launchany
APIs are a Conversation: Developer-to-Developer
Examples
and Guides
Reference
Docs
6. 6
@launchany
APIs are a Conversation: Human-to-Human
Homeowner:
“Can you tell me where
we stand with my home
remodeling project?”
Project Manager:
“Sure, here are the
tasks completed and
items remaining, along
with budget details”
8. 8
@launchany
Shifting the Conversation from Data APIs to Delivering Outcomes
Lowest value: API
consumers must build
their own outcomes
Highest value: where the
platform meets needs to
produce digital outcomes
IT Capabilities
(systems and data)
Platform Capabilities
(human-centric outcomes) Business Capabilities
(market-centric)
Shared
Technolog
y
Data
Sources
Legacy
Systems
Business
Processes
Market
and
Channel
Solutions
Platform
Capabilitie
s
(Platform
APIs)
Desired Outcomes
(Market-Driven)
Desired Outcomes
(Innovation-Driven)
Business Domain Events
(Reactive)
Business
Capabilitie
s
Business
Objectives
Market
Needs
9. 9
@launchany
Digital Products
enabled by APIs
Intended for outcomes
Platform APIs
Stability and reuse
Microservices
Decomposition and evolution
Apply product thinking
from the outside-in to
deliver outcomes to the
marketplace ...
… while delivering digital
capabilities combined
with product thinking and
ownership to drive reuse
Today: Focus has been on
microservices, but we are
losing the conversation for
the sake of decomposition
Customers
Internal
developers
Partners
Product thinking applied
Delivering Outcomes Requires API Refinement
11. 11
@launchany
What is API Quality?
• Aligned to the needs of the consumer, not the producer
• Maps business processes, not raw data
• Security from the start
• Outside-in design rather than code first
• Tested API design with feedback
Photo by MontyLov on Unsplash
12. 12
@launchany
Aligned to the Needs of the Consumer
The problem or triggering situation
The digital capability needed
The outcome desired
?
13. 13
@launchany
Aligned to the Needs of the Consumer
The problem or triggering situation
The digital capability needed
The outcome desired
APIs
deliver
outcomes
14. 14
@launchany
Maps Business Processes, Not Raw Data
• Using the outcomes as a guide, find the business processes necessary to deliver
upon the outcome
• Diagram out the process, or capture as a text-based narrative of each step
15. 15
@launchany
Incorporate API Security from the Start
•Map the persona that performs
each activity
•Some APIs may have the same
ones
•However, most APIs will have a
variety of personas and
authorization requirements
18. 18
@launchany
ALIGN
DEFINE
DESIGN
DELIVER
MANAGE
Design the digital capabilities as APIs, events, and
streams
DESIGN
Seek stakeholder alignment on desired outcomes
ALIGN
Improve the design based on early feedback
REFINE
Agree on digital capabilities required for desired
outcomes
DEFINE
Build, Deliver, Protect, monitor, and manage the digital
capabilities
DELIVER & MANAGE
The ADDR Collaborative API Design Process
ADDR
API Design
Process
19. 19
@launchany
Review: Refining Your API Design
• Aligned to the needs of the consumer, not the producer
• Maps business processes, not raw data
• Security from the start
• Outside-in design rather than code first
• Tested API design with feedback
Takeaway #1:
Is your API design process delivering higher-quality,
outcome-based API designs?
20. 20
@launchany
A Word of Caution about Microservices
Photo by Sen on Unsplash Photo by Karl Abuid on Unsplash
What we think when
we build
microservices
What we build using
microservices
22. 22
@launchany
Microservice Call Chains Create Increased Coordination
for Teams and the API Consumer
API Consumer Team #1 Team #2 Team #3
1) Coordinating
network traffic
and failure
coordination
2) Deployment and
change management
coordination
3) Error
messaging to
end user
coordination
API
23. 23
@launchany
Caution: The Coordination Cost of Too Many Fine-Grained Services
“In order to build a simple feature an engineer often has to work across
multiple services, all of which are owned by different individuals and teams.
This requires extensive collaboration with time spent on meetings, design, and
code review. The earlier promise of clear lines of service ownership is
compromised as teams build code within each other’s services, modify each
other’s data models, and even perform deployments on behalf of service owners.
Networked monoliths can form, where services that appear to be independent
all have to be deployed together to safely perform any change.”
https://eng.uber.com/microservice-architecture/
24. 24
@launchany
“Controlling the costs of
coordination will continue to be an
important issue as systems scale,
speeds increase, and the complexity
rises in the problems faced…”
Laura M.D. Maguire
https://queue.acm.org/detail.cfm?id=3380779
25. 25
@launchany
Use API Sequence Diagrams to Refine Your API Design Using Services
Does the addition of a
network boundary for the
microservice help or hinder
the API?
Does it introduce a
boundary within a
transaction?
26. 26
@launchany
Review: Microservices Don’t Always Yield Higher Reuse and Faster Delivery
• Every time we depend on another team for code, we slow down to wait
• Every time we have dependencies between teams, we slow down to have
meetings to coordinate our efforts
• The goal of microservices is to reduce coordination between teams…
• …but only if we apply the proper software architecture principles and practices
Takeaway #2:
Are Your Architectural and Design Decisions
Increasing or Decreasing Your Coordination Costs?
28. 28
@launchany
ADDR Process: Outcomes
• Aligns Business and Technology with Product Thinking
– Successful API design processes support collaboration across business, product, and technical teams.
• Improves Cross-Functional Communication
– Iterative, team-oriented process improves quality and speeds delivery
• Incorporates API Consumer Feedback
– Good API design relies on both iteration and parallel efforts with frequent feedback
• Avoids API Design Anti-Patterns
– Anti-patterns are usually signs that we learned important details too late.
• Delivers a Repeatable, Teachable Scalable Process
– The ADDR process guides groups through a repeatable, teachable, trackable process
29. 29
@launchany
Align-Define-Design-Refine (ADDR)
1. Identify digital capabilities
– Start with a set of job stories that capture the problem and job to be done
2. Capture activity steps
– Decompose the job stories into steps that produce the desired outcomes
3. Determine API boundaries
– Group capabilities to establish API boundaries
4. Model API profiles
– Produce a non-technical "API profile" document
5. Produce initial API design
– Select one or more API profiles and apply the desired API style(s)
6. Review/refine the design with stakeholders
– Review with stakeholders and refine design along the way
7. Document/package the API for self-service use
– Produce developer documentation, getting started guides, integration playbooks, etc.
https://bit.ly/api-design-book
A brief bit about myself. API Architect + API strategy and execution. Development background.
Across multiple verticals: Commercial Insurance, Healthcare, Hospitality, Finance and Banking, Travel, Airline
Recently wrote a book…
City elevation: 6,035ft / 1,839 m
Pike’s Peak elevation: 14114,17ft / 4,302 m
Intentional design
To improve the quality of our APIs, we need to understand the types of API conversations
First, APIs are a conversation between machines. This is what most of us as developers know and love. HTTP methods, JSON structures, response codes. We live and breathe this stuff
Thinking a bit more about the conversation, there is also the developer-to-developer conversation. The API provider, the one that builds the API, needs to help the API consumer to understand how to use it. API reference documentation and getting started guides are common for this kind of conversation.
Ultimately, the conversation is human-to-human. What is it that someone is trying to do? And how are we helping them get there? Ultimately, we need to model these as APIs to support the human outcomes desired
Homeowner: “Can you tell me where we stand with my home remodeling project?”
Project Manager: “Sure, here are the tasks completed and items remaining”
Policy Holder: “I’m trying to list the recently submitted claim so that I can track the status as I get back to whole”
Adjuster: “Sure, I can provide you with that information”
API-First mindset is used to unbundle the business lifecycle into a composable set of APIs that enable the optimization and innovation of digital products, experiences, and business models.
Product Mindset Vision:
To achieve proper reuse and productization, it is important to recognize that enterprises are complex. They require domain areas that are specific to the business. This is an example of a hospitality platform. Each area is owned by a product manager and the overall portfolio is managed by the platform team. When this is done, the result is a more modular enterprise that is composed of services, events, message streams, and APIs that support the needs of the workforce, partners, and customers
To get there, we need to bring together our IT capabilities (on the left) and business capabilities (on the right) into a Global Insurance API platform. This platform offers APIs, events, and streams that are sourced from existing systems to deliver digital outcomes.
When many first start their digital transformation journey, we noticed that everyone was skilled in delivering services. However, there was a gap in understanding the outcomes that the APIs would deliver. We needed to shift from “code first” to address “what outcomes will the API deliver”.
With the foundation of APIs as a conversation underway, let’s look at some patterns and practices that help improve your API design, API quality, and API security
We use job stories in our ADDR API design process to surface the problems and desired outcomes. The digital capability needed to solve the problem and produce the desired outcome is where our APIs live
We use job stories in our ADDR API design process to surface the problems and desired outcomes
To overcome these coordination costs, we encouraged teams to apply the ADDR process to find proper boundaries before decomposing their solutions into services. Along the way, we continue to see how this shift is impacting API designs for the better. We’ve seen teams apply the ADDR process successfully by starting with the desired outcomes and driving toward an API design that delivers upon those desired outcomes. API Designer Certification in MCDC
The following dependency diagrams demonstrate how complexity increases with microservices. Especially if smaller and smaller microservices are used.
Coordination costs increase when we need more teams to deliver an outcome. Or to coordinate transactions across the network. Or to troubleshoot runtime issues across multiple distributed components.
Death star diagrams: https://www.divante.com/blog/10-companies-that-implemented-the-microservice-architecture-and-paved-the-way-for-others
Death star: https://starwars.fandom.com/wiki/Death_Star_(disambiguation)
Each call in a service call chain creates more coordination. This coordination includes network traffic(machine-to-machine), delivery traffic (developer-to-developer), troubleshooting at runtime(developer-to-developer), and error messaging back to the API consumer and resulting end-user (human-to-human)
However, we need to learn lessons from others that have struggled with microservices early on. Many built out very small services that created increased network chattiness and fragility. Uber found out about this and has since shifted their approach on services to more course-grained services rather than fine-grained services. They also worked toward adjusting their service boundaries to better meet their delivery needs.
Laura Maguire discusses the impact of coordination costs on anomalies that disrupt reliable service delivery
sequenceDiagram
participant Customer
participant Shopping API
Customer->>Shopping API: GET /books
Shopping API-->>Customer: Books[]
Customer->>Shopping API: POST /carts { bookId: 12345, qty: 1 }
Shopping API-->>Customer: Cart { cartId: 456 }
Customer->>Shopping API: DELETE /carts/456/items/1
Customer->>Shopping API: POST /books/search { q: "API" }
Shopping API->>Book Search Service: POST /books-index?q=API
Book Search Service->>Search Engine: POST /books-index?q=API
Search Engine-->>Book Search Service: SearchResults
Book Search Service-->>Book Search Service: convertResultsToBookResources
Book Search Service-->>Shopping API: Books[]
Shopping API-->>Customer: Books[]
Customer->>Shopping API: POST /carts/456/items { bookId: 12345, qty: 1 }
Shopping API-->>Customer: Cart { cartId: 456, ... }
Customer->>Shopping API: GET /carts/456
Shopping API-->>Customer: Cart { cartId: 456, ... }