Ce diaporama a bien été signalé.
Le téléchargement de votre SlideShare est en cours. ×

APIs with Bounded Contexts: Modelling Apis with Domain-Driven Design

Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité
Publicité

Consultez-les par la suite

1 sur 27 Publicité

APIs with Bounded Contexts: Modelling Apis with Domain-Driven Design

Télécharger pour lire hors ligne

APIs have become one of the cornerstones of digital transformations. As more and more businesses open up their APIs for public consumption, the concept of developer experience becomes crucial for the successful rollout of the APIs. Good developer experience with APIs depends on good principles of API governance, API management, and API design.

In this presentation, we explain how the principles of domain-driven design help us design APIs that are easier to understand and to consume. APIs are not just an HTTP interface to a database, and we’ll see how to use DDD to define the domain of an API and to model its resources. We’ll use strategic design to narrow down the scope of an API, and to avoid mixing properties from different domains. We’ll also discuss various heuristics that we can use to translate domain models and actions into the more restricted representational capabilities of REST APIs and CRUD operations.

The result of this exercise will be a well-structured API with consistent paths and resources that developers will love to use to and to build integrations with.

APIs have become one of the cornerstones of digital transformations. As more and more businesses open up their APIs for public consumption, the concept of developer experience becomes crucial for the successful rollout of the APIs. Good developer experience with APIs depends on good principles of API governance, API management, and API design.

In this presentation, we explain how the principles of domain-driven design help us design APIs that are easier to understand and to consume. APIs are not just an HTTP interface to a database, and we’ll see how to use DDD to define the domain of an API and to model its resources. We’ll use strategic design to narrow down the scope of an API, and to avoid mixing properties from different domains. We’ll also discuss various heuristics that we can use to translate domain models and actions into the more restricted representational capabilities of REST APIs and CRUD operations.

The result of this exercise will be a well-structured API with consistent paths and resources that developers will love to use to and to build integrations with.

Publicité
Publicité

Plus De Contenu Connexe

Plus récents (20)

Publicité

APIs with Bounded Contexts: Modelling Apis with Domain-Driven Design

  1. 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. 2. $ whoami • I’m Jose • Consultant, author, instructor • Author of Microservices and APIs • Founder of microapis.io @JoseHaroPeralta @microapisio 35% discount code: ctwapiworld22
  3. 3. microapis.io 39% discount code: ctwapi21 One-click API mock servers @JoseHaroPeralta @microapisio
  4. 4. Connect with me!  Twitter: @JoseHaroPeralta  GitHub: @abunuwas  Medium: @joseharoperalta /@python-geek  LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/
  5. 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. 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. 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. 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. 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. 10. Starting with an experiment • We started with a small experiment • Early Machine Learning iterations proved successful
  11. 11. Building a PoC • Built a quick UI using Dash (Python library) • Weekly iterations
  12. 12. PoC validated – project kicks off Split UI and backend 1 Expose backend API 2 Operate at scale 3
  13. 13. Project kicks off – new architecture
  14. 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. 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
  16. 16. God models: using states instead of entities
  17. 17. Bad models
  18. 18. 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
  19. 19. From states to entities Raw forecast Scenario Candidate Submission New store forecast
  20. 20. 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
  21. 21. 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
  22. 22. Use meaningful resource endpoints and leverage HTTP semantics
  23. 23. 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
  24. 24. Thanks for listening! Twitter: @JoseHaroPeralta GitHub: @abunuwas Medium: @joseharoperalta /@python-geek LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/ 35% discount code: ctwapiworld22
  25. 25. 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)
  26. 26. 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)

×