APIs with Bounded Contexts: Modelling Apis with Domain-Driven Design
Download as PPTX, PDF1 like196 views
The document outlines the importance of using Domain-Driven Design (DDD) for effective API modeling, emphasizing that understanding processes and flows leads to better API design rather than just focusing on endpoints. It highlights challenges faced in projects, particularly with data-driven applications and common anti-patterns such as cluttered endpoints and oversimplification through CRUD. The conclusion stresses the need to avoid rigid models, focus on meaningful operations, and recognize that changing APIs can be risky, advocating for clarity and discrete resource models.
APIs with Bounded Contexts: Modelling Apis with Domain-Driven Design
- 1. APIS WITH BOUNDED CONTEXTS Modelling APIs with Domain-Driven Design José Haro Peralta Consultant and instructor Founder of microapis.io API World Conference 28 Oct – 3 Nov 2022 @microapisio @JoseHaroPeralta
- 2. $ whoami • I’m Jose • Consultant, author, instructor • Author of Microservices and APIs • Founder of microapis.io @JoseHaroPeralta @microapisio 35% discount code: ctwapiworld22
- 3. microapis.io 39% discount code: ctwapi21 One-click API mock servers @JoseHaroPeralta @microapisio
- 4. Connect with me! Twitter: @JoseHaroPeralta GitHub: @abunuwas Medium: @joseharoperalta /@python-geek LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
- 5. Agenda Complexity of creating good API design More in particular, good REST API design How domain-driven design helps to design better APIs Special case of data-driven applications
- 6. Ubiquitous APIs • Using domain-driven design to align with the business helps us create better APIs • Think about processes and flows instead of endpoints and HTTP status codes • How leveraging API design principles such as uniform interface helps us create ubiquitous APIs • Leveraging HTTP semantics helps us create ubiquitous APIs
- 7. Reality is more complex than textbook cases • Many projects start out as an experiment and/or PoC and then there’s pressure to build the production application quickly (the business case often depends on the speed of delivery) • In reality, we often figure out what we’re doing on the go (the domain and the subdomains become clear as we progress in our work) • The business often lacks terminology to refer to their own processes and flows and to their own “entities” • Data-driven applications are notoriously hard to model (everything is “data”)
- 8. APIs for data-driven applications anti-patterns • API conceived as data gateways • Lack of API design and validation • Lacking notion of operations • Oversimplification through CRUD (CRUDified APIs) • God models • Cluttered endpoints • Lacking HTTP semantics • Breaking uniform interface
- 9. Build a sales forecasting application • Digital transformation project in major international retail org • Automate sales forecasting • From two forecasts a year to rolling forecast • More accurate forecast • Being able to model multiple scenarios • Keep track of historical forecasts and compare
- 10. Starting with an experiment • We started with a small experiment • Early Machine Learning iterations proved successful
- 11. Building a PoC • Built a quick UI using Dash (Python library) • Weekly iterations
- 12. PoC validated – project kicks off Split UI and backend 1 Expose backend API 2 Operate at scale 3
- 13. Project kicks off – new architecture
- 14. API design challenges • It becomes clear that the business lacks terminology to refer to their own processes and flows, and to their “entities” • Different countries use different processes and flows • We think of states instead of different entities and we have a “God model”
- 15. API design challenges • We drag bad models from the PoC • Cluttered endpoints due to over-reuse • Very difficult to continue extending the API • 2 languages: business and data science
- 17. God models: using states instead of entities
- 18. Bad models
- 19. Cluttered endpoints • POST /forecast => retrieve raw forecast • POST /forecast + adjustments => create scenario • POST /forecast + adjustments + new stores => create new store forecast • PUT /forecast/{forecast_id} => create candidate • PUT /forecast/{forecast_id} => create submission
- 20. From states to entities Raw forecast Scenario Candidate Submission New store forecast
- 21. Modeling operations • Stop thinking in terms of URLs and HTTP methods • Start thinking in terms of operations • Decouple your backend data model from your API models • Leverage HTTP semantics • Enforce uniform interface
- 22. Start with operations, processes, and flows • Retrieve raw forecast • Create and update scenarios • Create and update candidate • Create submission • Create forecasts and scenarios for new stores
- 23. Use meaningful resource endpoints and leverage HTTP semantics
- 24. Conclusions • Changing the API is risky – can break integrations => address design issues early • Don’t think in terms of URLs and HTTP methods => think in terms of operations, processes, and flows • Don’t crudify your APIs – if an operation isn’t needed, don’t add it • Flexible models are bad => create discrete models for each entity • Clarity over reusability => don’t reuse endpoints and models
- 25. Thanks for listening! Twitter: @JoseHaroPeralta GitHub: @abunuwas Medium: @joseharoperalta /@python-geek LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/ 35% discount code: ctwapiworld22
- 26. ADDITIONAL READINGS • Microservice APIs by J. Haro (mng.bz/nz48) • “Building and deploying reliable APIs with FastAPI” by J. Haro (https://www.twitch.tv/videos/1088283640) • Documentation-driven development for APIs by J. Haro (https://link.medium.com/m2A3rOxUfib) • “Developing API clients doesn’t need to be a pain” by J. Haro (https://link.medium.com/0B9vt7DUfib) • “How bad models ruin an API” by J. Haro (https://microapis.io/blog/how-bad-models- ruin-an-api) • “API-first development maturity framework” by J. Haro (https://microapis.io/blog/api- development-maturity)
- 27. ADDITIONAL READINGS • “Design patterns for modern web APIs” by D. Luecke (https://blog.feathersjs.com/design-patterns-for-modern-web-apis-1f046635215) • The design of web APIs by A Lauret (https://www.manning.com/books/the-design-of- web-apis) • Designing APIs with Swagger and OpenAPI by J. S. Ponelat and L. L. Rosenstock (https://www.manning.com/books/designing-apis-with-swagger-and-openapi) • API Design Patterns by JJ Geewax (https://www.manning.com/books/api-design- patterns) • Principle of Web API Design by J. Higginbotham (https://www.pearson.com/store/p/principles-of-web-api-design-delivering-value- with-apis-and-microservices/P200000007278/9780137355631)