REST API next level - crafting domain driven web APIs

src: REST next level : Crafting domain driven web APIs By Julien Topçu

Abstract
PB #1: false beliefs

Nouns vs Verbs debate is not a debate: we can have verbs in the URI

PB #2: confusing the business and the model

exposing our model to our consumer ⇒ accidental complexity of adaptation

PB #3: the encapsulation betrayal

encapsulate the states to expose behaviors

we have to read the payload to deduce the use case ⇒ loss of meaning through de-encapsulation Example:
# Accidental Complexity of adaptation
PATCH /searches/{id}/selection
[{
  "op": "add",
  "path": "/selectedSpaceTrains/...",
  "value": {
    "trainNumber": "MOON421",
    "fare": "FIRST
  }
}]
# understand the intent based on the URI
# back-end doesn't have to change on the model
POST /searches/{id}/spaceTrains/{number}/fares/{code}/select
How does the front-end know it can do this?

PB #4: anemic API regarding the workflow

how do we know that we must proceed in the API order?

only the front-end is implementing the business workflow

HATEOAS: Hypermedia As The Engine of Application State

a linking system (URLs) allowing you to:

expose the relationships between the domain objects

discover the domain

encapsulate the business workflow

the front-end must not try to understand how the URLs are formed

⇒ better decoupling between the consumption and the implementation of the domain model

REST impendance mismatch

❌ false beliefs on the REST nomenclature

✅ using verbs enrich the semantic of the API

❌ straight exposition of our model in the API

✅ business-oriented endpoint on the back-end

❌ exposing the states of the domain objects

✅ encapsulation of behaviors attached to the responsible objects in the API

❌ lack of workflow definition (anemic API)

✅ HATEOAS to drive workflow from the API

Spring framework HATEOAS supportS