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.

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)