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

16.
God models: using states instead of entities

17.
Bad models

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.
From states to entities
Raw forecast
Scenario
Candidate
Submission
New store
forecast

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.
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.
Use meaningful resource endpoints and
leverage HTTP semantics

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.
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.
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.
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)