Teams often struggle with balancing the complexity of legacy applications, limited time, and limited resources when designing APIs. The result is often the release of less-than-ideal API design that meets the immediate needs of the client but misses opportunities for longer-term value. This talk explores systems design and domain-driven design (DDD) for API design thinking and how to apply this technique to your design process to create a clear, well-designed, long-lasting API. Presented at API Strategy and Practice 2015

1. APIs Are Forever:
How to Design Long-Las6ng APIs
James Higginbotham
API Architect
@launchany

2. Your API tells a story.
What story does yours tell?

3. If your API is the story,
you are doing it wrong.

4. Do we create one API product?
More than one product?
How can we prevent a redesign?

5. Architecture is design

6. Web APIs are an architectural
concern that expose an interface to
an underlying system.
Design them to tell your story.

7. “We have a monolithic app, but we
are in the process of rearchitecDng
it using microservices and APIs.”
-- anyone where code.age >= 3 months

8. Why do we have
“monolithic regret” and how
can we avoid it?

9. Lack of Modulariza6on = Regret
VS
Func6on-Based Module-Based

10. (Re)Introducing Systems Design
and Domain-Driven Design

11. Modeling a System
System/Solu6on
Subsystem Subsystem
Module Module
Module Module
Subsystem Subsystem
Module Module

12. The System of LEGO
System
Sub-systems
Modules

13. “Your API design should become
the definiDon of your new
target architecture“ - @jharmn

14. MulD-Sided Marketplace
PlaRorm API Example

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

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

17. Each subsystem has an API that
exposes one or more endpoints.

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

19. IdenDfying the products
becomes easier when we have
boundaries around the APIs

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

21. For every API, ask:
“What are your resources?”

22. Domain-Driven Design

23. Model domain objects to find
business enDDes, relaDons,
state transiDons, and events

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

25. Order API
Availabili6es
Orders
Products
(Inventory)
Bookings
Inventory API
Fulfillment API
Same data,
Conceptually different to
the API consumer!

26. AvailabiliDes
- product
- date(s) avail
- qty avail
Orders
- bookings
- order total
Products
- name
- avail schedule
Bookings
- product
- date(s)
- status

27. AvailabiliDes
- product
- date(s) avail
- qty avail
availabilityChanged()
Orders
- bookings
- order total
created()
updated()
Products
- name
- avail schedule
created()
removed()
updated()
Bookings
- product
- date(s)
- status
redeemed()
cancelled()

28. PuXng it all together

29. AvailabiliDes
- product
- date(s) avail
- qty avail
availabilityChanged()
Orders
- bookings
- order total
created()
updated()
Products
- name
- avail schedule
created()
removed()
updated()
Bookings
- product
- date(s)
- status
redeemed()
cancelled()
Order API Inventory API
Fulfillment API

30. Where do microservices fit?

31. AvailabiliDes
Service
createAvailability()
updateAvailability ()
deleteAvailability ()
…
availabilityChanged()
Orders Service
createOrder()
updateOrder ()
deleteOrder ()
…
created()
updated()
Products Service
createProduct()
updateProduct ()
deleteProduct ()
…
created()
removed()
updated()
Bookings Service
lookupBooking()
redeemBooking ()
cancelBooking ()
…
redeemed()
cancelled()
Order API Inventory API
Fulfillment API
Orders HTTP API Inventory HTTP API
Fulfillment HTTP
API

32. How does your API design
reflect your API story?

33. Thank you!
James Higginbotham
james@launchany.com
@launchany