O'Reilly SACon San Jose, CA - 2019 - API design tutorial

1
Bridging the Gap
Mapping a Domain Model
to a RESTful WEB API
O’Reilly Software Architecture Conference – San Jose CA, June 11th , 2019
Tom Hofte & Marco van der Linden | Xebia | The Netherlands
#OReillySACon

Let’s start with some networking!
Take some time to introduce yourself to your neighbours:
→What company or organisation you are from
→What do you expect from this tutorial
→Any other things you would like to share

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
(from 3:00pm)
Other Topics &
Conclusion
~ 20 minutes
(4:30pm)

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

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

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

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

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
REST is the web architectural style underpinning the web
and HTTP is THE web protocol following REST

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

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

…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:
• Which domain entities
and attributes?
• Operational
granularity?
• …

Example: Webshop
Customer
Domain REST
Address
Customer
Address
internalId
referenceId
firstname
lastname
addressId
status
groupID
De-normalized in a single REST resource
Checkout
Order
???
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>

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 an API that is
intuitive, consistent and extensible.
“While 25% say they are only using a design-first
approach, 22% say they are using both the design
first and code-first approach. One-third of the
respondents that currently use code-first only say
they are moving to a design-first approach.”
More teams are moving to a design-first approach
Source:
https://smartbear.com/SmartBearBrand/media/pdf/SmartBear_State
_of_API_2019.pdf

Resource Modeling Process
Discover the API
domain for your
business domain
Discover the REST
resources &
operations
Implement the API
interface

API Style Guide inspiration (apistylebook.com)

Part 1 – Discover the API domain

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

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

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

Find your domain operations
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, which are the API operations

Granularity
Confirm Booking
(update order, confirm &
payment,)
Set Customer
Info
Set Delivery
Info
Set Payment
Method
Confirm
Payment
Set xxx Requires
previous
steps
Fine-grained
Transaction flow logic
Client-side
ü Highly flexible, if the transaction flow is
not strict
☝ Increased client complexity: clients need to
understand strict transaction flow logic
☝ Chatty API
Course-grained
Transaction flow logic
Server-side
ü Minimized Client Complexity
ü Server logic hidden
☝ Less flexibility when
transaction logic is not strict
Where your API will be:
• Maximize Client-side flexibility
• Minimize Client-side complexity
Update Order Confrm & Payment

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

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

Discover your API model
Example: Partial domain model
Shopping Ordering

Exercise 1: Discover the API Domain

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

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

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

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

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_sacon

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?

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

Part 2 – REST resource modeling

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

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

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

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

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

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

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

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’
• YAGN

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

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

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)

REST Operations – Resource Operation Patterns
Sometimes it can be difficult or inefficient to intuitively model an API operation, which spans multiple
resources or is asynchronous of character, using the HTTP methods:
An operation is a function to do a
calculation/look up with a
synchronous response
An operation triggers an event
with an optional asynchronous
response
{api}
Request - Response
{api} {api}
Request (fire-forget)
Asynchronous Response
Poll
Push
Response
(Resources)
ready

REST Operations – Function Pattern
A verb in your URI path representing a function
→Server response: answer and HTTP 200
→Typically modelled with GET as request / reply
Expedia API: https://developer.ean.com/documentation/rapid-shopping-docs
{api}
Request - Response

REST Operations – Event-driven operation
A noun representing an asynchronous event
→Long running
→Event can be monitored
→Typically modelled with HTTP POST as fire-and-
forget
→Server response HTTP 202 ACCEPTED
REST without PUT / CQRS
Source: GitHub API

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

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

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

Exercise 2: Discover REST resources and
operations

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 diagram
→A Swagger file specification

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

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_sacon

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

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

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

Rate today ’s session
Session page on conference website O’Reilly Events App

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

O'Reilly SACon San Jose, CA - 2019 - API design tutorial

More Related Content

What's hot (13)

Similar to O'Reilly SACon San Jose, CA - 2019 - API design tutorial (20)

Recently uploaded (20)

O'Reilly SACon San Jose, CA - 2019 - API design tutorial