Presented at GlueCon 2016. Applying good software engineering practices, system design, and domain-driven design for your public APIs and microservices
23. Domain Driven Design (DDD)
Maps domain concepts into software
Heavy domain expert involvement
Common vocabulary (“Ubiquitous Language”)
Boundary-driven (“Bounded Context”)
Applies learning over time
24. “I need to multiply two numbers
together. So, I am building
a microservice architecture.”
- almost everyone today
25. Microservice Architecture
Loosely-coupled, service-oriented architecture
Apply bounded context to limit cognitive load
Independently deployable via automation
Enable replaceability and experimentation
Encourage composability of the business
Best for larger teams
28. 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
29. 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
31. 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
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
Operator
Remove
Product
Inventory API
Fulfillment API
#1 #2
`
Point
Of Sale
36. 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
43. Public APIs target durability
through external contracts.
Microservice APIs target evolution through
learning and experimentation
44. Availabilities Service Orders Service
Products Service
Bookings Service
Orders HTTP API
Inventory HTTP API
Fulfillment HTTP API
45. Availabilities Service Orders Service
Products Service
Bookings Service
Orders HTTP API
Inventory HTTP API
Fulfillment HTTP API
Payment Service Refund Service
47. 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
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…
Capital One is changing the way we interact with banking and bank-level security
Released 3 APIs during SXSW in March
Watson is changing the way we UNDERSTAND DATA
LANGUAGE, SPEECH, VISION, and DATA INSIGHTS
Marvel is changing the way we INTERACT with the ENTERTAINMENT MEDIA and their storytelling
Characters, stories, comics, creators, and events
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…
You may not be at Stripe’s scale or mission critical for customers
How you version your API design over time is important, however – IT IS A CONTRACT
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.
Even when we, as designers, MISS THE MARK, we should OWN IT
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
Our DATABASES are not our API
Our CODE (classes, functions) are not our API
Our API is a contract that is implemented by our code and databases
We must put ourselves IN THE PLACE OF THE CONSUMER, NOT THE DEVELOPER
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
<<ADV…>>There are several popular web frameworks that make building a monolithic application easy – almost trivial.
These frameworks commonly offer: accelerated development, but left off modular design
This leads to a lack of proper modularization, impacting our API designs
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
High Cohension – common functionality that is related BELONG TOGETHER
Loose coupling – reduced dependencies across modules - minimize cohesion across modules
Public APIs define the contract that the top module is offering to other modules around it. If the API contract changes, either through a change in the inputs, outputs, or overall behavior, it can break the integration between these modules.
To prevent other modules from interacting with the internal components of itself, we apply scoping rules to restrict access
Systems: This is a completely independent system that provides a solution to one or more problems
Subsystems: Bounded concerns that help to compose the system itself. Subsystems do not offer a solution on their own, but contribute a bounded portion of it. finally, Modules: These are the building blocks for composing subsystems. Modules may contain one or more components, where components are classes in object-oriented programming languages or functions in functional programming languages.
Demonstration of LEGO of how to BREAK a big KIT (problem) into smaller, manageable modules
ALIGN OURSELVES based on core competencies
APIs provide the opportunity to connect subsystems, with internal APIs that connect modules together. We should ONLY KNOW what the subsystem APIs are, NOT THE MODULE APIs
Approach on software development for complex needs
Based on Eric Evans' book "Domain Driven Design”
Adrian Cockcroft’s definition
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
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
PRODUCT INVENTORY
PRODUCT AVAIL + ORDERS
BOOKINGS
EVENTS – often the MOST 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
Github callbacks expanded the development pipeline beyond a single tool vendor
[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
Start with services for each root-level domain entity
Use SERVICE OBJECTS or MICROSERVICES
Starting with the simplest services, we can break services out as we dig into the implementation details.
In this case, PAYMENT and REFUND can be broken out and assigned to a different team
API Gateways offer public contracts, integrate with microservices
We live in a world with a growing number of APIs
Many APIs represented in this room and at this conference
Let’s look for skills and capabilities around us, build APIs, and HELP OTHERS TELL A STORY