This document discusses applying domain-driven design principles to API and microservices architecture. It recommends using an outside-in design approach where the data model is separate from the object model and resource model. Domain-driven design helps identify context boundaries, and microservices require renewed focus on system and API design. Modeling the domain entities, relations, states and events defines the resources exposed by each API. This modular design increases composability and the ability to replace services over time.
13. API Design is an architectural
concern that combines business
drivers, product design, and
software design
14. Outside-In API Design Approach
“My data model is not my object model”
– Data model is for internal storage
“My object model is not my resource model”
– Resources is for external, context-based collaboration
– Object model is for internal software collaboration
“My resource model is not my representation model”
– There are many ways to represent resources
e.g. JSON, XML, CSV, HTML
- Mike Amundsen, API-Craft Google Group
- https://groups.google.com/forum/#!search/my$20resource$20model$20is$20not/api-
craft/n2Efmju5nLM/KUEyMOFIBAAJ
19. Domain Driven Design (DDD)
Mapping domain concepts into software
Heavy focus on domain expert involvement
Common vocabulary (“Ubiquitous Language”)
Boundary-driven (“Bounded Context”)
Applies learning over time
Based on Eric Evans' book "Domain Driven
Design”
23. Microservice Architecture
Microservices are independently deployable,
loosely-coupled components
Apply bounded context to limit cognitive load
Benefit from heavy automation (CI/CD)
Enable replaceability and experimentation
Encourage composability of the business for
new products
29. List Avail
Inventory
Distributor
Add Product
to Order
Complete
Order
Cancel
Booking
Add Product
to Inventory
Update
Product Qty
Locate
Booking
Redeem
Booking
Point
Of Sale
Remove
Product
Customer
Operator
Operator
30. Order Mgmt
List Avail
Inventory
Distributor
Add Product
to Order
Complete
Order
Cancel
Booking
Add Product
to Inventory
Update
Product Qty
Locate
Booking
Redeem
Booking
Operator
Point
Of Sale
Remove
Product
Customer
Operator
Inventory Mgmt
Fulfillment
33. Order API
List Avail
Inventory
Distributor
Add Product
to Order
Complete
Order
Cancel
Booking
Add Product
to Inventory
Update
Product Qty
Locate
Booking
Redeem
Booking
Point
Of Sale
Remove
Product
Customer
Operator
Inventory API
Fulfillment API
Operator
35. Order API
List Avail
Inventory
Distributor
Add Product
to Order
Complete
Order
Cancel
Booking
Add Product
to Inventory
Update
Product Qty
Locate
Booking
Redeem
Booking
Operator
Remove
Product
Inventory API
Fulfillment API
#1 #2
`
Point
Of Sale
38. Order API
List Avail
Inventory
Add Product
to Order
Complete
Order
Cancel
Booking
Add Product
to Inventory
Update
Product Qty
Locate
Booking
Redeem
Booking
Remove
Product
Inventory API
Fulfillment API
48. The Composable World of APIs
Offers API
Inventory
API
Bookings
API
Identity API
Accounts
API
Rewards
API
Partners
Internal
Developers
Public App
Developers
Consumers
Third-party
Approved Apps
49. Summary
Great API design is critical for product adoption
and long-term API success
API Design is an architectural concern that
combines business drivers, product design, and
software design
Systems design and DDD help with designing
long-lasting APIs
Use microservices where appropriate to increase
composability of your business or product
Be a storyteller using APIs
We’re going to talk about how to design LONG-LASTING APIs. The goal is to avoid a redesign not long after your API is deployed.
API TRAINING to help coach teams on how to think in APIs and apply the techniques I’ll show you today
Across every team and company, I reiterate one common theme…
At their core, APIs are contracts for software component interaction.
How we design our APIs will drive the level of short and long-term success.
As an example, STRIPE…
Stripe is well known because they focus on great API design and documentation.
But it extends beyond that. They tell a story with their API: “we power commerce for businesses of all sizes”
Everything is built around that…
Medhi recently tweeted that Stripe maintains 50 (actually now closer to 65) different versions of their API.
They OWN VERSIONING, rather than pushing it to the CONSUMER.
Event when we, as designers, MISS THE MARK
Their API TELLS A STORY…
FINTECH is exploding and Capital One is leading the way
3 APIs…
Publicly sharing their processes, lessons, and future vision at SXSW
Watch the videos
Watson offers a variety of services for developing cognitive applications
LANGUAGE, SPEECH, VISION, and DATA INSIGHTS
Characters, stories, comics, creators, and events
Kin Lane has been conducting API workshops at universities by showing how to ACCOMPLISH THINGS
Zapier/IFTTT is his model for teaching the use of APIs
Ticketmaster demonstrates how skills may vary based on a role or context – we will focus on this kind of API for the purposes of this talk
This requires applying proper API design techniques
Does your API reflect getting things done, or pushing data around?
MOST SIGNIFICANT DESIGN DECISIONS
Software design, not ivory tower architects
WE ARE ALL software architects – we all make significant design decisions AT SOME POINT in the life cycle
Web APIs are an architectural concern, but MORE THAN THAT – PRODUCT AND BUSINESS
TODAY IS HTTP, TOMORROW may be something else
Use architectural design techniques to drive your API design
What is it we are trying to solve and how are we planning to solve it?
THAT IS THE PRODUCT SIDE and WHAT IS MOST EXCITING TO ME
Since we have to look at APIs as part of (or) a complete product, it requires OUTSIDE-IN design approaches
Mike Admundsen wrote about this on a recent API craft google group
I want to SHARE what METHODS I have USED to HELP TEAMS DESIGN APIs
Product development = opportunity + need + solution
Systems design defines how your product is architected
API Systems design tells 2 stories: about how your API is architected (internal-facing), and how your API works within other solutions (external-facing)
Ecommerce example – what does it take to place an order?
These are the skills that our API must offer
Essential step #1
Next step is finding our APIs, product boundaries, and resource boundaries
This is where our agile techniques such as REFACTORING and iterative development
<<ADV…>>There are several popular web frameworks that make building a monolithic application easy – almost trivial.
These frameworks commonly offer: accelerated development, code generation, open source plugins/extensions, simplified deployment and the ability to scale out by adding more instances as required to support the current load.
The problem is that they encourage poor software architecture unless carefully monitored. This leads to a lack of proper modularization...
10 years, new frameworks, but they assume a single subsystem – the webapp or “site”
They missed the mark for larger applications, trying to avoid SOA
This is leading to “MONOLITHIC REGRET” and a lack of modular applications
Microservices is becoming a common way to deal with this problem at LARGER SCALES
Systems: SOLUTION to PROBLEM(s)Subsystems: BOUNDED CONCERNSModules: BUILDING BLOCKS for Composition
Demonstration of LEGO of how to BREAK a big KIT (problem) into smaller, manageable modules
ALIGN OURSELVES based on core competencies
Independent systems combined into a larger solution
Each built by teams or TEAMS OF TEAMS
Constrained on what I can share
Extract concepts to demonstrate the process
First step – list, understand what the business requirements were, how different parties were to interact with the system
Group related activities participant(s) need to perform into subsystems
Use the boundaries to determine:
- what has already been built in-house
- what needs to be built in-house
- what can be replaced by COTS, third-party APIs
We found 2 stories: a distributor story and an operator story = 2 PRODUCTS
Operators vs Distributors drove API DESIGN, DOCS, MARKETING
Different vocabularies for distributors and operators
Not “what are your endpoints” or “what are your URLs”
Discuss aggregates, entities, and value objects. Aggregates become resources, named after the root entity within
Goal: Consistent naming that reflects the API’s intended use
EVENTS – often MISSED OPPORTUNITY
Callbacks change the way developers interact with you API, from POLLING to automatic NOTIFICATION when things change.
Allows them to be more reactive to change in your own subsystems
[recall early in the talk: when is my product ready to launch?]
Our architecture shows us not only what we need to build, but what each party needs to accomplish their goals/solution.
This helps us with product roadmaps, scheduling, and other internal aspects of product management.
Durability == LONG LASTING
Replaceability == AGILITY, EXPERIMENTATION, EVOLUTION
HTTP is just a gateway to your underlying subsystems.
Systems design help us find those boundaries
Domain-driven design help us find our service boundaries
Events tie them together