A presentation given by Jose Haro Peralta Consultant, Author, and Instructor, Microapis.io, at our 2023 Platform Summit, October 17-18, 2023.

1. APIs with Bounded Contexts
Better design with domain-driven APIs
José Haro Peralta
Consultant, author, and instructor
Founder of microapis.io
Platform Summit
Oct 16-18, 2023

2. $ whoami
• I’m Jose
• Consultant, author, instructor
• Author of Microservice APIs
• Founder of microapis.io
• Creator of fencer
@JoseHaroPeralta
@microapis

3. Relio
https://getrelio.com/

4. Connect with me!
 Twitter: @JoseHaroPeralta
 GitHub: @abunuwas
 Newsletter: https://microapis.substack.com
 LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/

5. Agenda
 Why is API design difficult?
 How DDD helps us design better APIs
 How do we model flows?

6. SmartBear’s State of Software Quality | API 2023

7. API-First

8. API design is difficult
Raw materials:
 URLs
 HTTP methods
 Status codes
 Schemas
 HTTP headers

9. APIs are contracts with the external world

10. Inside-out
API design

11. Inside-out API design

12. List a historical log of user consent events
Returns information about the status of an Item.
List a user’s connected applications

15. Outside-in API design

16. What is DDD?
 Align software with business
 Incorporate the language of the business
 Create a Ubiquitous Language
 Under the processes and flows of the business
 Facilitate conversations between software and business

17. Domains, subdomains, and bounded contexts
 Domain represents the core area of the business
 Subdomain represents a specific area of the business
 A bounded context is a space within which the vocabulary
acquires specific meaning

18. Sources:
• https://www.amdocs.com/insights/blog/event-storming
• https://developer.ibm.com/tutorials/reactive-in-practice-1/

19. How do we model operations in APIs?
1. Customer searches the catalogue
2. Customer adds items to the cart.
3. Customer proceeds to check out.
4. After applying coupons, the system calculates the price.
5. Customer selects a payment method and enters payment details.
6. System processes payment.
7. System confirms the order.

20. We identify user flows and domains in the API

21. Heuristics for modeling operations
 How do we model payment?
 Paying is an operation, not an object or resource
 Semantics of a POST => create a resource or send data for
processing
 POST will process the payment and create a payment object
in our server
 Return the outcome of this operation to the user
 Using this heuristic, we can model nearly every business
operation through the API.

22. Heuristics are a
means to an end
CRUD heuristic
 Create
 Read
 Update
 Delete
CRUD vs CRUDE
APIs

23. Cross-domain user flows

26. How do we model flows in APIs?
How do we represent the relationship between endpoints to
document the flow?
 HATEOAS
 OpenAPI links
 Workflows

27. Documenting flows with HATEOAS

28. Documenting flows with OpenAPI links

29. Documenting flows with workflows

30. https://github.com/OAI/sig-workflows

31. Further reading
 I wrote some thoughts on bringing DDD and API design together in “APIs with
Bounded Contexts”.
 An insightful and pioneering overview of how domain-driven design can help
and empower the API design process is James Higginbotham’s Principles of
Web API Design. Another great resource that encourages a DDD approach to
API design is Patterns for API Design, by Olaf Zimmerman, Mirko Stocker,
Daniel Lübke, Uwe Zdun, and Cesare Pautasso.
 For a comprehensive overview of API design, check out Arnaud Lauret’s The
Design of Web APIs. David Biesack’s newsletter API Design Matters is also a
rich source of ideas and information about good API design.
 For more about API design heuristics for REST/OpenAPI, check out Josh
Ponelat and Lukas Rosenstock’s Designing APIs with Swagger and
OpenAPI. Check out Lukas’s talk “From Domain Model to API” for more
examples of heuristics.
 For ideas on modelling complex concepts like trust and liability, check out
Martin Verraes and Rebecca Wirfs-Brock’s article “Models and Metaphors”.

32. Thanks for listening!
Twitter: @JoseHaroPeralta
GitHub: @abunuwas
Newsletter: https://microapis.substack.com
LinkedIn: https://www.linkedin.com/in/jose-haro-peralta/