Building Flexible APIs with Spring HATEOAS

GregLTurnquist.com/springone2020
Building Flexible APIs
with Spring HATEOAS
September 2–3, 2020
springone.io
1

Who am I?

Who am I?
bit.ly/hacking-with-spring-boot

Who am I?
bit.ly/hacking-with-spring-boot
● Principal developer on
the Spring team
● Nashville JUG co-founder
● Committer & Project
Lead for several Spring
projects
● YouTube/GregTurnquist

Let’s talk about…APIs!

What is an API?

What is an API?
● Place to get a little JSON/XML/whatever?

What is an API?
● Way to interact with the app?

What is an API?
● Means to extract value from another app to help your own app?

What is an API?
● Means to extract value from another app to help your own app?
Let’s dig in and discover what it means to have a flexible API!

Simple API
6
● Spring MVC
● Simple
● Clear separation between layers

Simple API
{
"id": 0,
"name": "Frodo",
"role": "ring bearer"
}
6

Simple API
{
"id": 0,
"name": "Frodo",
}
6
● Data and…

Simple API
{
"id": 0,
"name": "Frodo",
}
6
● Data and…
● …nothing else!

Simple API
{
"id": 0,
"name": "Frodo",
}
6
● Data and…
● Some value, but what about…

Simple API
{
"id": 0,
"name": "Frodo",
}
6
● Data and…
● …updates?

Simple API
{
"id": 0,
"name": "Frodo",
}
6
● Data and…
● …updates?
● …breaking changes?

Simple API
{
"id": 0,
"name": "Frodo",
}
6
● Data and…
● …updates?
● …breaking changes?
● …backwards compatibility?

What happens when…
6

What happens when you serve this…
{
"id": 0,
"firstName": "Frodo",
"lastName": "Baggins",
}
6

…but older clients try this?
6

6
● What now?

6
● What now?
● Tell users to just use your new API?

6
● What now?
● Roll out another version?

6
● What now?
● Roll out another version?
● Handle this AND the new format?

What about versioning?
6
https://www.infoq.com/news/2013/12/api-versioning/
● Knot = Single version of API
● P2P = Multiple versions
● Compatible = One API supports
multiple versions

What about versioning?
6
It is always possible for some unexpected reason to come along that requires a completely
different API, especially when the semantics of the interface change or security issues require the
abandonment of previously deployed software. My point was that there is no need to anticipate
such world-breaking changes with a version ID. We have the hostname for that. What you are
creating is not a new version of the API, but a new system with a new brand.
On the Web, we call that a new website. Websites don’t come with version numbers attached
because they never need to. Neither should a RESTful API. A RESTful API (done right) is just a
website for clients with a limited vocabulary.
—Dr. Roy Fielding
“

How rough can deprecating APIs be?
6
http://bit.ly/deprecating-apis

Just do this…
6

Just do this…
6
● “Never delete a
column”

Just do this…
6
column”
● Handle new
clients

Just do this…
6
column”
● Handle new
clients
● Support old
clients

Just do this…
6
column”
● Handle new
clients
● Support old
clients
● Everyone wins!

What else do you need?

● Hypermedia controls

● Instead of telling someone how to use your API on a portal…

● …give them the controls right in the API

● …using standard media types

● It’s how the web functions

● It’s the reason the web succeeded

● It’s the reason the web succeeded
● The reason everyone today builds web apps

Just migrate from this…
6

…to this!
6

{
"id": 0,
"role": "ring bearer",
"name": "Frodo Baggins",
"_links": {
"self": {
"href": "http://localhost:8080/rest/employees/0"
},
"employees": {
"href": "http://localhost:8080/rest/employees"
}
},
…
So you can do this!
6
● New clients

{
"id": 0,
"_links": {
"self": {
},
"employees": {
}
},
…
So you can do this!
6
● New clients
● Old clients

{
"id": 0,
"_links": {
"self": {
},
"employees": {
}
},
…
So you can do this!
6
● New clients
● Old clients
● Navigate between related
components

…and this
6
…
"_templates": {
"default": {
"method": "put",
"properties": [
{
"name": "firstName"
},
{
"name": "id",
"readOnly": true
},
{
"name": "lastName"
},
{
"name": "name"
},
{
"name": "role"
}
]}}}
● New clients
● Old clients
components
● Effect change

…
"_templates": {
"default": {
"method": "put",
"properties": [
{
"name": "firstName"
},
{
"name": "id",
"readOnly": true
},
{
"name": "lastName"
},
{
"name": "name"
},
{
"name": "role"
}
]}}}
…and this
6
● New clients
● Old clients
components
● Effect change

…
"_templates": {
"default": {
"method": "put",
"properties": [
{
"name": "firstName"
},
{
"name": "id",
"readOnly": true
},
{
"name": "lastName"
},
{
"name": "name"
},
{
"name": "role"
}
]}}}
…and this
6
● New clients
● Old clients
components
● Effect change (even for
old clients!)

Consuming Hypermedia

What if…

What if…
● You wanted your client to consume hypermedia?

What if…
● Ready to register all those messy message converters?

What if…
● Do you really want to look up how to customize RestTemplate (or
WebClient) to handle HAL, HAL-FORMS, etc., etc., etc.?

What if…
● Do you really want to look up how to customize RestTemplate (or
WebClient) to handle HAL, HAL-FORMS, etc., etc., etc.?
Spring HATEOAS has you covered!

RestTemplate support

We also support WebClient
● Inject WebClient.Builder into your app
● …and .build()!

😳Not in production!

Additional Features

Additional Features
● Spring WebFlux support

Additional Features
● More media types (UBER+JSON, Collection+JSON, Your Own ™)

Additional Features
● Standardized errors with Problem+JSON (RFC-7807)

Additional Features
● Lots of performance improvements

Additional Features
● Increasing community involvement
● JSON:API, Siren media types
● Document updates
● New ideas!

Additional Features
● Increasing community involvement
● JSON:API, Siren media types
● Document updates
● New ideas!
Check it out!

Thank you SpringOne 2020!
Join me on #session-building-flexible-apis-with-spring-hateoas
for Q&A
Follow us on twitter @SpringHATEOAS
Visit GregLTurnquist.com/springone2020 to WIN a
paperback+ebook copy of Hacking with Spring Boot 2.3

Building Flexible APIs with Spring HATEOAS

More Related Content

What's hot (20)

Similar to Building Flexible APIs with Spring HATEOAS (20)

More from VMware Tanzu (20)

Recently uploaded (20)

Building Flexible APIs with Spring HATEOAS