Refining Your API Design - Architecture and Modeling Learning Event
0 likes525 views
The document discusses the importance of refining API design to align more with consumer needs rather than producers. It emphasizes outcome-driven APIs that map business processes and incorporate security from the start, while also critiquing the coordination challenges presented by microservices. The 'align-define-design-refine' process is proposed as a collaborative approach to improve API quality and delivery.
![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", … }, … ]](https://image.slidesharecdn.com/vaughn2023-refiningyourapidesign-230515162227-a74dbf00/85/Refining-Your-API-Design-Architecture-and-Modeling-Learning-Event-4-320.jpg)
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”
- 3. 3 @launchany APIs are a Conversation Photo by Harli Marten on Unsplash
- 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”
- 7. 7 @launchany Availability Reservations Billing Policy Staffing Bookings Partners Internal developers Public app developers Customers Third-party approved apps 7 Conversations Across the Digital Organization
- 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
- 10. 10 @launchany Refining Your API Design Photo by Francisco Fernandes on Unsplash
- 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
- 16. 16 @launchany Outside-in Design Rather than Code-First
- 17. 17 @launchany Tested API Design with Feedback
- 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
- 21. 21 @launchany Caution: Microservice Dependencies Create Increased Coordination Galactic Empire
- 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?
- 27. 27 @launchany “Align-Define-Design-Refine” ADDR Collaborative API Process https://bit.ly/api-design-book
- 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
Editor's Notes
- #2: How do we improve the quality of our APIs?
- #3: 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
- #4: To improve the quality of our APIs, we need to understand the types of API conversations
- #5: 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
- #6: 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.
- #7: 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”
- #8: 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
- #9: 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.
- #10: 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”.
- #11: 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
- #13: 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
- #14: We use job stories in our ADDR API design process to surface the problems and desired outcomes
- #19: 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
- #22: 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)
- #23: 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)
- #24: 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.
- #25: Laura Maguire discusses the impact of coordination costs on anomalies that disrupt reliable service delivery
- #26: 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, ... }