Mind The Gap - Mapping a domain model to a RESTful API - OReilly SACon 2018, London

1. 1
Mind the Gap
Mapping a Domain Model
to a RESTful WEB API
O’Reilly Software Architecture Conference – London October 31th , 2018
Tom Hofte & Marco van der Linden | Xebia | The Netherlands

2. Agenda – 3.5 hours
Introduction & API
Domain discovery
~ 20 minutes
API Domain
discovery
~ 45 minutes
REST Resource
modeling
~ 20 minutes
REST Resource
modeling
~ 60 minutes
Coffee Break
~ 15 minutes
(10:45)
Other Topics &
Conclusion
~ 20 minutes
(12:30)

3. Part 0 - Introduction

4. Living in an API Economy
APIs allow companies to grow and extend businesses at unprecedented rates
by sharing services with third parties – source: Harvard Business Review (https://hbr.org/2015/01/the-strategic-value-of-apis)
{api}
{api}
Note: Slide picture inspired by an idea of Willem van Schieveen, Bol.com

5. What we, techies, used to think an API is
With the rise of web technologies, the term API now represents a business
product and is a unique selling point on the web
Component A Component B
API
Remote
CORBA
DCOM
RMI
SOAP WS
Local

6. An API is a business service with a web access point
that is managed as a product
We think a public API
• is an open or partner service
• that exposes business capabilities
• through consumer-friendly operations
• that are used to built new applications
• accessible from a web access point
• and follows a product life cycle
API
Private Public
OpenPartner

7. A typical API value stream:
A RESTful API as the channel to your domain
But why REST?
Business Domain Model
containing data entities,
logic and operationsDomain
Message-based
Interface contract
RESTful API Interface
API Consumers
Own devices,
partners or open
Inside Out
Outside In

8. An API needs a web architecture that provides a uniform interface
that decouples the client from the server and scales with the web.
{json},
</xml>
Resources and methods to transfer state
and links between resources to walk
through the resources. Together they form
the view on the domain model
Different clients on a
heterogeneous network
HTTP
Caching
URI Format
Request Message
Format
Response Message
Format
HTTP Methods
Scalability
HTTP as the web transfer protocol that
provides a uniform interface to support
decoupling on a heterogeneous network
such as the web
That are some goals of REST and HTTP is a web protocol following REST

9. REST ‘Myths’
• REST = HTTP
• REST = CRUD
• A REST resource is a database table
• A REST API needs to be versioned
• REST = Simple

10. REST in Theory versus REST used in Practice:
A RESTful API is generally referring to a HTTP interface using a set of URLs
Source: https://martinfowler.com/articles/richardsonMaturityModel.html
Where most RESTful APIs are

11. …how do you create a RESTful API contract for your domain?
Domain
RESTful API Interface
Describing complex
domain behavior
in a REST manner
is not straightforward

12. Example: Webshop
Customer
Domain REST
Address
Customer
Address
internalId
referenceId
firstname
lastname
addressId
status
groupID
De-normalized in a single REST resource
Create
customer
POST customers
Domain Operations
mapped to
REST operations
{ "customer":{
"referenceId":
"1234"
"firstName": "John"
"lastName": "Doe"
"Address":
{...}
}
}
Representation of
required attributes
in JSON, XML or ..
<customer>
<referenceId>1234</refere
nceId>
<firstName>John<firstName
>
<lastName>Doe</lastName>
<Address>
<...>
</Address>
</customer>

13. Resources are the core of a RESTful API…
Resource modeling is therefore a key activity to…
• Map your domain operations to RESTful operations
• Map your domain entities to RESTful resources and
representations
…in order to create a set of API design rules to get
an API that is intuitive, consistent and extensible.

14. Resource Modeling Process
Discover the API
domain
Discover the REST
resources &
operations
Implement the API
interface

15. API Design Rules inspiration (apistylebook.com)

16. Part 1 – Discover the API domain

17. Start with the business domain
Inside domain
Outside API domain
Outside API Model ⊂ Inside Business Model

18. Create a Ubiquitous Language
A shared language to reason
about the domain.
Protest against any form of:
• Ambiguity
• Inconsistencies

19. Model your domain
Create one or more models of your domain.
Identify all entities and their associations.
Use bounded contexts to group behavior
and keep your models readable.
Bounded contexts:
• Logically groups behavior (business
capabilities)
• Makes explicit what the model is for
• Limits dependencies between domains
• structures the later implementation

20. Find your domain events (and commands)
You can gain better understanding of the domain by looking at the events that
occur, in the domain and with other domains.
Events are triggered by commands.

21. Analysis methods
• Input:
→Use case descriptions
→Domain experts, external and internal
• Methods:
→Event storming or other types of workshop
→Text and domain analysis (verbs and nouns)
• Output
→Logical domain models depicting:
Ø Sets of nouns (entities) and verbs (operations) grouped in models (with bounded contexts)
Ø Relations between entities

22. Discover your API model
Example: Partial output using verbs and nouns
CustomersProduct Shopping Cart Order
Search products
Execute
Payment
Checkout
Shopping Cart
View products in
shopping cart
Add product to
shopping cart Payment
Create Order
Approve
Order
Shopping Ordering Customers
Add
customer
Change
customer
OrderItem
Product

23. Discover your API model
Example: Partial domain model
Shopping Ordering

24. Exercise 1: Discover the API Domain

25. ractice how to discover API domain entities, relations and operations that you need in your API
√
Goal:
Practice how to discover API domain entities,
relations and operations that you need in your API

26. Exercise Input - Case Description: FlyWithMe airline
FlyWithMe is an airline that wants to increase sales by extending its current business
model towards third parties. They plan to do this by providing a Public API.
You are an architect at FlyWithMe, responsible for designing the API.
You and your team decide to start with discovering the domain entities and
operations
…more input is provided in the hand-outs

27. Exercise outcome
• List of domain entities
• List of domain operations
• Grouped by “bounded context”
• Time left? Try to define the entity relations

28. Tips
• Don’t try to over-complicate the business domain; the goal is not to
get a complete understanding of the domain.
• Make assumptions about the business domain where needed
• Focus on API consumer functionality
• Do not focus on the attributes of an entity, solely focus on the nouns
and verbs

29. And now to work!
• Organize yourselves in groups of 3-4
• Work on exercise for the next 45 minutes
• Make use of paper, flip overs (easel pad) etc. to visualize your answer.
Case material: http://bit.ly/restfulapidesign_saconeu

30. Retro time
• Which entities and operations did you discover?
• Where you able to visualize the model(s) and draw in the
relationships?
• What discussions did you have?
• Which assumptions did you make?

31. REST API Resource Modeling Process
Discover the API
domain
Discover the REST
resources &
operations
Define the API
interface

32. Part 2 – REST resource modeling

33. Goal
• Learn how to map domain entities and operations to REST resources and
operations
• Learn about API documentation options
• Practice by modelling basic use cases from the case study

34. From a domain model to a REST contract
A typical flow
Domain
Entities
Domain
operations
Step 3 – Define the API in a specification
language
• Determine the resource representations
• Operation granularity
Step 1 – Create sequence diagrams
• Group related domain operations in user
stories
Step 2 - Map to REST
• Translate domain operations and entities
to REST resources and operations

35. REST API specification language
• Start defining the API using a API description languages:
→Open API (fka Swagger)
→RAML
→ API Blueprint
• Kickstart your development with an API design tool
→SwaggerHub
→Confluence + swagger.io plugin

36. Anatomy of a RESTful API
Resource Operations = VERBS such as GET | POST | PUT | DELETE
Resources representations = NOUNS representations = Media Types (JSON, XML, …)
resources = NOUNS
Resource location = URI
resources relations

37. REST resources
Document: A single document with optional subresources
• https://api.flywithme.com/flightoffers/{id}
Collection: A server managed collection: a plural noun
• https://api.flywithme.com/airports
The key abstraction of information in REST is a resource. Any information that can be
named can be a resource: a document or image, a temporal service (e.g. "today's
weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a
person), and so on. - Roy Fielding
Source: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

38. REST Resource Relations – Types of Relations
Order
Customer
existentially dependent
non-existentially
dependent
OrderItem
OrderItem
OrderItem
1 N
Order
N
1

39. REST Resource Relations - Modeling
Resource modeling options:
Linked Resources
{
orderId: 1
...
customerId: 1
...
}
Embedded resources
{
id: 1
...
orderItems:
[
{
id: 1
product: "X"
.. }
]
}
Path modeling rules:
• non-existentially dependent
customers{customerid}
• existentially dependent
orders{orderid}orderitems{orderitemid}
Use projection/included flags to mix linked and embedded resources:
GET orders{orderid}?include=customer
GET orders{orderid}?projection=status

40. REST Resource Relations – Modeling – HATEOAS
(Hypermedia as the Engine of Application State) – Richardson Maturity Model – Level 3
Intensions – Browse through the API
like browsing the content on a website
• Self describing, explorable API
• Standard message structure
• Support API evolution
{. ”orderId": 2
”orderItems”: [
1,2,3,4
]
"links": [
{
"href": ”1/orderitems",
"rel": ”GET order items",
"type" : "GET"
},
{
"href": "1/seats",
"rel": ”seats",
"type" : "GET"
}
]
]
GET ../orders/{orderId}
DELETE ../orders/{id}
GET .. ../orders/{id}/orderitems/{id}/products
GET ../orders/{id}/orderitems
Warning!
• Clients using hard-coded ‘deep-links’

41. REST Resource Representations – Media Types
Mime-types used most often in the Content-Type header:
→application/json
→application/xml
But binary content is also possible:
→Content-Type: application/pdf
Or create a vendor JSON media type for structured JSON:
→ application/vnd.api+json

42. REST Resource Representations – Hypermedia
Standardized message structure to
support HATEOAS:
• HAL
• SIREN
• JSON-LD
• …
API Response
Resource State
{JSON}
Links
Embedded Resources
href:
rel:

43. REST Operations - Standard HTTP methods
GET https://api.flywithme.com/airports/{airportid}
Retrieve resources
POST https://api.flywithme.com/bookings body: trip
Create a new resource
PUT https://api.flywithme.com/bookings/{bookingid} body: updated trip
Update (Replace) an existing resource completely (idempotent)
DELETE https://api.flywithme.com/bookings/{bookingid}
Delete an existing resource
PATCH https://api.flywithme.com/bookings/{bookingid}/passengers body: email
Partially update an existing resource (non-idempotent)

44. REST Operations – Resource Operation Patterns
Sometimes it can be difficult or inefficient to intuitively model a business capability spanning multiple
resources with fine-grained HTTP methods:
→ A business capability can be a long-running process with an optional asynchronous response
→ A business capability can be a function
Add non-CRUD verbs or noun-ified verbs to your API and leverage the URI path

45. REST Operations – Function Pattern
A verb in your URI path representing a function
→ Typically modelled with GET
Expedia API: https://developer.ean.com/documentation/rapid-shopping-docs

46. REST Operations – Command pattern
A noun representing an asynchronous action
→Long running
→Action can be monitored
→Typically modelled with HTTP POST
REST without PUT / CQRS
Source: GitHub API

47. REST Operations - Webhook pattern
Event-driven integration via server callbacks
• Flight updates
• Price changes
Polling is bad for everyone
• ~95% of polling requests are useless
• Reduce load on server

48. REST operation response codes
Developer friendly response by reusing HTTP response code semantics
• Range 2xx – Client message has been received, understood and processed succesfully
• E.g. Use HTTP 201 when a resource is created
• Range 3xx – Location redirection
• Range 4xx – Request could not be processed due to an error caused by the client
• Range 5xx – Request could not be processed due to an error caused by the server

49. Evolving the API
API Change Strategy
• Only version on MAJOR
• Make backwards compatible changes (MINOR, PATCH) and avoid breaking changes
(MAJOR)
In case you need to make breaking changes:
• Facilitate an API life cycle plan to not take functionality abruptly away
• Have a communication plan towards your consumers
Changes will happen, so define a change
strategy

50. Exercise 2: Discover REST resources and
operations

51. Exercise input
Take the output of exercise 1 and …
→Take your team result
→Or take our example result
Look at the 2 user stories (*) and define a RESTful API by
→Creating a sequence flow diagram
→A Swagger file specification

52. Tips
• Don’t try to over-complicate the business domain; the goal is not to
get a complete understanding of the domain.
• Make assumptions about the business domain where needed
• Focus on API consumer functionality
• Do not focus on the attributes of an entity, solely focus on the nouns
and verbs

53. Exercise outcome
For each of the 2 user stories:
• Sequence flow diagrams highlighting the REST operations and resources
• An initial swagger file specifying the REST operations and resources needed to
implemented the user stories

54. And now to work!
• Work on the exercise for the next 60 minutes
• Make use of
→https://www.websequencediagrams.com
→https://editor.swagger.io
→https://swagger.io/specification/
Case material: http://bit.ly/restfulapidesign_saconeu

55. Coffee Break

56. Running out of material, but not out of time?
You can add the following features:
• Notify partner websites with flight updates
• Update bookings

57. Retro time
• What went well?
• What was difficult?

58. REST API Resource Modeling Process
Discover the API
domain
Discover the REST
resources &
operations
Define the API
interface

59. Final Thoughts

60. An API is a product

61. Key Learning Points
1. A RESTful API is a channel into your business domain
2. A RESTful interface <> business domain model
3. You need to set your REST maturity ambition and agree on
a consistent set of design guidelines
4. Don’t be afraid of changes, but facilitate them in your API
design and in the communication to your API consumers

62. Tom Höfte,
IT
TUTORIAL
Thank you for
attending!
Tom Hofte, Solution Architect, Xebia, thofte@xebia.com
Marco van der Linden, Solution Architect, Xebia, mvanderlinden@xebia.com