REST API next level - crafting domain driven web APIs

src: REST next level : Crafting domain driven web APIs By Julien Topçu - Invidious

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