book

Crafting Great APIs with Domain-Driven Design : Collaborative Craftsmanship of Asynchronous and Synchronous APIs

Name: Crafting Great APIs with Domain-Driven Design : Collaborative Craftsmanship of Asynchronous and Synchronous APIs
ISBN: 9798868814570

by Annegret Junker, Fabrizio Lazzaretti

October 2025

Intermediate to advanced

412 pages

11h 47m

English

Apress

Read now

Unlock full access

Crafting Great APIs with Domain-Driven Design
Introduction
Conventions UsedImportant InformationBackground InformationCodeChapter OverviewChapter 1, “Transforming Problematic Application Programming Interfaces”Chapter 2, “Communication Categories”Chapter 3, “Quality Requirements for APIs”Chapter 4, “Online Library”Chapter 5, “API Design Supported by Domain-Driven Design”Chapter 6, “Interface Definitions”Chapter 7, “Defining the Online Library Interfaces”Chapter 8, “Developer Experience and API Implementation”Chapter 9, “Collaborative Design and Agility”Chapter 10, “Iterative Enhancements”Chapter 11, “Brownfield Project”Chapter 12, “Shortcuts in the Process”Chapter 13, “APIs and Events in a Serverless World”Chapter 14, “Avoiding Mistakes in the Definition of Events and APIs”Chapter 15, “A Couple of Beautiful APIs”Chapter 16, “Summary”
Preface
Acknowledgements
Contents
About the Authors
About the Technical Reviewer
Part I: The Importance of API Design
1. Transforming Problematic Application Programming Interfaces
Complexity in a Volatility, Uncertainty, Complexity, and Ambiguity (VUCA) WorldComplexityVUCA WorldThe Term APIAPIs Nobody Wants to UseAn API Taken Directly from a DatabaseAn API Formulated Solely from the Backend Developer’s Point of ViewA Purely Technical API Without Business RelevanceAn API from the Ivory TowerOverloaded World-Domination APIAPIs Without Documentation and Unexpected BehaviorIntroduction to Modern Development ProcessesCollaborative Approaches Improve ProcessesWhy a Modern Development Process Is Necessary and ValuableAPI-First vs. Code-FirstPoints to RememberReview Questions
2. Communication Categories
The Term APICommunication in GeneralMessages as the Central Building BlockCommunication Styles and MechanismsCommunication Types: Synchronous and Asynchronous CommunicationSynchronous CommunicationAsynchronous CommunicationAsynchronous Communication with BrokersCommunication and APIsCommunication Mechanisms, Architectural Patterns, and Suitable ProtocolsRequest- and Response-Based MechanismsMessaging vs. EventingMessagingEventingPoints to RememberReview Questions

3. Quality Requirements for APIs
Functional SuitabilityFunctional CompletenessFunctional CorrectnessFunctional AppropriatenessPerformance EfficiencyTime BehaviorResource UtilizationCapacityCompatibilityCoexistenceInteroperabilityInteraction CapabilityAppropriateness RecognizabilityLearnabilityOperabilityUser Error ProtectionUser EngagementInclusivityUser AssistanceSelf-DescriptivenessReliabilityFaultlessnessAvailabilityFault ToleranceRecoverabilitySecurityMaintainabilityModularityReusabilityAnalyzabilityModifiabilityTestabilityFlexibilityAdaptabilityScalabilityInstallabilityReplaceabilitySafetySummaryReview Questions
Part II: Domain-Driven API Design
4. Online Library
First Requirements GatheringFirst Implementation IdeasStart of PrioritizationPoints to RememberReview Questions
5. API Design Supported by Domain-Driven Design
Qualifying Business IdeasBusiness Model CanvasCapability MapWardley MapPrioritization of CapabilitiesGathering Business RequirementsDomain StorytellingIntroduction to Domain StorytellingDomain Story for Searching and LendingDomain Story for Reading and SharingIndividual Reading ListTeaching and Reading to ChildrenCatalog ManagementVisual GlossaryVisual Glossary Lending and SearchingVisual Glossary ReadingVisual Glossary Reading to ChildrenEvent StormingIntroduction to Event StormingEvent Storming of Online LibraryContext MapShared KernelCustomer/Supplier Development TeamsConformistAnticorruption LayerSeparate WaysOpen Host ServicePartnershipBig Ball of Mud (BBoM)Discussion of Data Exchange Using API-First ApproachDiscussion of Synchronous APIsSynchronous APIs for Data ExchangeSynchronous APIs for User InteractionsDiscussion of EventsGeneration of API Definitions with AIConclusionPoints to RememberReview Questions
6. Interface Definitions
Components of an Interface DefinitionShort History of Interface DefinitionsWSDL, RAML, Swagger, and OpenAPIWSDLRAMLSwaggerOpenAPIAsyncAPINecessary Information for InterfacesComponents of an Interface Definition for Synchronous and Asynchronous InterfacesInformation BlockServersPathsChannelsOperationsSchemasData Formats and Their SchemasJSONYAMLXMLProtobufAvroComparison of Data FormatsConclusionIdempotency and GuaranteesProblems in TransmissionMitigating ProblemsDefinition of Synchronous InterfacesDefinition as gRPCDefinition as GraphQLDefinition as REST with OpenAPIIntroduction to RESTOpenAPIComparison of gRPC, GraphQL, and HTTP RESTDefinition of Asynchronous InterfacesAsyncAPISpecification in DetailChannelsOperationsMessage and Schema DefinitionSecurity SchemesDifferent Scenarios for AsyncAPIBrokerless Async CommunicationWhat AsyncAPI MissesCloudEventsAdvantages and Disadvantages of Different Schemas and ProtocolsSchemaless Versus Schemafull with Respect to the Single Data FormatsRead and Write Functions and Their Advantages and DisadvantagesTooling for LintingCompression During TransitNorth–South and East–West CommunicationDecision Tree Use of Schemas and ProtocolsTypical AntipatternsSynchronous EventsAsynchronous CommandsMessages as EventsHuge EventsAI Generation of API Definitions: Chances and LimitationsConclusionPoints to RememberReview Questions
7. Defining the Online Library Interfaces
IntroductionBounded Context CanvasArchitecture Communication CanvasAPI Product CanvasInventory ManagementDefinition of AsyncAPIDefinition of OpenAPICatalog ManagementManagement ApplicationSearch ApplicationLendingReadingAppointment ManagementTeaching and Reading to KidsMember ManagementConclusionPoints to RememberReview Questions
Part III: Enabling Transformation
8. Developer Experience and API Implementation
Versioning of APIsWhat Is a Breaking Change?Backward, Forward, and Full CompatibilityConsider If a New Version Number Is the SolutionSynchronous APIsAsynchronous APIsSchema RegistryTestingTypes of TestingStatic Code Tests and LintingCompilerUnit TestsContract TestingIntegration TestsE2E TestsConceptsTest-Driven DevelopmentBehavior-Driven TestingConclude TestingContinuous IntegrationGit FlowContinuous DeploymentBenefits and Use of CI/CD with APIsConclusionPublishing APIsAPI Management PlatformAPI GatewayAPI MarketplaceBackends for Frontends (BFF)Service MeshAPI DiscoveryApiOps as a ProcessDeveloper Experience When Integrating an APISandboxObservabilityAbility to Get HelpSoftware Development Kits (SDKs)Common StandardsData Mesh ConceptAnalytics and MonitoringError DiscoveryUsage Insights into APIsBilling with MetricsAnalyzing PerformanceConclusionPoints to RememberReview Questions
9. Collaborative Design and Agility
Collaborative Design ProcessBusiness ModelStrategic DesignDomain StorytellingEvent StormingContext MapTactical DesignOverviewNecessary Mindset for API DesignNecessary MindsetAdditional Methodologies in the ProcessBusiness Process Model NotationUser Story MappingBehavior-Driven DesignExample MappingConway’s LawTeam TopologiesCollaborative Processes in Classical Project EnvironmentsSpotify ModelFlight LevelsShort Feedback Loops and Stable APIsConclusionPoints to RememberReview Questions
10. Iterative Enhancements
Adding New FeaturesAdding a Small Feature ExtensionEnhancement of Online Library by Completely New FeaturesIntegration of External InterfacesStandardizationCollaboration Between PartnersPublishing Events to External PartnersPublishing External EventsSecurity ConcernsConclusionPoints to RememberReview Questions
11. Brownfield Project
Hypothetical Insurance Legacy SystemLegacy SystemBusiness Analysis in a BrownfieldDomain Storytelling of Current ProcessIntended ProcessArchitectural Approach to Modernization for the Insurance ApplicationBusiness Analysis Using Wardley Map MethodArchitectural TransitionTechnical AnalysisDecoupling LayerModernization LayerDeveloped ArchitectureConclusionPoints to RememberReview Questions
12. Shortcuts in the Process
North StarDefinition of REST APIs Directly After Domain StorytellingDefinition of Events Directly from Event StormingTactical DesignConclusionPoints to RememberReview Questions
13. APIs and Events in a Serverless World
New Requirements and Challenges in the CloudThe CAP Theorem and Eventual ConsistencyUsing the Cloud’s BenefitsWhat Is Serverless?How to Implement APIs Without a ServerPoints to RememberReview Questions
Part IV: Summarizing
14. Avoiding Mistakes in the Definition of Events and APIs
Revisiting the Examples from the BeginningAn API Directly from the DatabaseAn API Solely Formulated from the Backend Developer’s Point of ViewA Purely Technical API Without Business RelevanceAn API from the Ivory TowerThe Overloaded World-Domination APIAPIs Without Documentation and Unexpected BehaviorOther ProblemsConclusionPoints to RememberReview Questions
15. A Couple of Beautiful APIs
What Is a Beautiful API in the Eyes of the Authors?Some Beautiful Real-World APIsSynchronous APIsAsynchronous APIsConclusionPoints to RememberReview Questions
16. Summary
Solutions
Review Questions for Chapter 1Review Questions for Chapter 2Review Questions for Chapter 3Review Questions for Chapter 4Review Questions for Chapter 5Review Questions for Chapter 6Review Questions for Chapter 7Review Questions for Chapter 8Review Questions for Chapter 9Review Questions for Chapter 10Review Questions for Chapter 11Review Questions for Chapter 12Review Questions for Chapter 13Review Questions for Chapter 14Review Questions for Chapter 15
Glossary
References
Index

Content preview from Crafting Great APIs with Domain-Driven Design : Collaborative Craftsmanship of Asynchronous and Synchronous APIs

A. Junker, F. LazzarettiCrafting Great APIs with Domain-Driven Designhttps://doi.org/10.1007/979-8-8688-1457-0_16

16. Summary

Annegret Junker¹ and Fabrizio Lazzaretti²

Having shown how mistakes in APIs can be mitigated, and having looked at some beautiful real-world APIs, we are in a position to conclude the book.

In the book we went from “what is an API?” and “what is quality?” to “how do we specify an API?” and “how can we collaboratively arrive at an elegant API” to “which processes should I use?” Here, we would like to summarize the tools and methods learned and put them in context: from tactical to strategic ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges

Publisher Resources

ISBN: 9798868814570Purchase Link Publisher Website

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Crafting Great APIs with Domain-Driven Design : Collaborative Craftsmanship of Asynchronous and Synchronous APIs

by Annegret Junker, Fabrizio Lazzaretti

16. Summary

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.