Consumer-centric API Design

Consumer
centric API Design
Arrows designed by FreePik

ÜBER MICH
Microservices maßgeschneidert | Arne Limburg
• Enterprise Architect bei der open knowledge GmbH
• Themen
• Microservices
• Domain Driven Design
• APIs
• Architektur
• Coaching
• Technologie (Java EE / Jakarta EE)
Arne Limburg

ÜBER OPEN KNOWLEDGE
Titel der Präsentation | Name des Sprechers
Branchenneutrale Softwareentwicklung und IT-Beratung

#WISSENTEILEN
// Retrieve all products
GET /products
// What about searching, filtering, pagination?
// Retrieve single product
GET /products/1234
// What about buying it?
// i.e. putting to shopping cart, payment, etc.
REST
„URLs“

Wisely choose HTTP
Methods and Resources

#WISSENTEILEN
// Retrieve all customers
GET /customers
// Retrieve single customer with ID 1234
GET /customers/1234
REST
„URLs“

#WISSENTEILEN
// Retrieve single customer with id 1234
GET /customers/1234
// Retrieve all addresses of customer 1234
GET /customers/1234/addresses
// Retrieve address 5 of customer 1234
GET /customers/1234/addresses/5
REST
„root“

#WISSENTEILEN
GET /customers/1234/addresses
// vs.
GET /addresses/?customerNumber=1234
REST
„root“

#WISSENTEILEN
// Path parameter for identifier
GET /customers/1234
// Query parameter for queries (optional)
GET /customers/?status=verified
// Header parameter for platform (optional)
GET /customers/1234
Accept-Language: de-DE
REST
„param“

#WISSENTEILEN
// Body parameter for resource
PUT /customers/1234
{
... CUSTOMER DATA ...
}
REST
„param“

#WISSENTEILEN
// register customer
POST /customers
{ ... initial customers data ... }
// read customer e.g. to check status
GET /customers/1234
// change customer
PUT /customers/1234
{ ... some changes ... }
// remove customer
DELETE /customers/1234
REST
„method“

#WISSENTEILEN
// „Create new customer“.
POST /customers
// Is this allowed? Guess not. Is it?
POST /customers/1234
// „Change customer“. I‘am sure! But wait ...“
PUT /customers/1234
// „Change customer“, too? Isn‘t it?
PATCH /customers/1234
REST
„method“

#WISSENTEILEN
POST vs. PUT vs. PATCH
POST
erzeugt Child Resource an Server-definierter URI
PUT
erzeugt/ändert Child Resource an Client-definierter URI
PATCH
ändert Teile einer Child Resource an Client-definierter URI

#WISSENTEILEN
// Creates customer. Returns ID 1234
POST /customers
{ ... payload for 1234 ... }
// Hmmm, updates customer 1234? Creates new customer?
POST /customers
{ ... payload for 1234 ... }
REST
„method“

#WISSENTEILEN
// Changes customer with ID 1234
PUT /customers/1234
{ ... changes for 1234 ... }
// Hmmm, will be ignored?
PUT /customers/1234
{ ... changes for 1234, e.g. add e-mail address ... }
// Or additional changes?
PUT /customers/1234
{ ... changes for 1234, e.g. add more e-mail addresses ... }
REST
„method“

#WISSENTEILEN
// Changes customer with ID 1234
PUT /customers/1234
{ ... changes for 1234 ... }
// Same as PUT? Mayby not!
{ ... changes for 1234 ... }
// Same as PUT? Is this what i expect?
GET /customers/1234?status=verified or
GET /customers/1234/setVerified
REST
„method“

#WISSENTEILEN
SAFE / IDEMPOTENT Methods
SAFE*
keine Änderung an der Ressource
IDEMPOTENT**
einmalige Änderung an der Ressource-Repräsentation
mehrfache Wiederholung führt immer zum selben Ergebnis
* GET, HEAD, OPTIONS
** GET, HEAD, OPTIONS, PUT, DELETE

#WISSENTEILEN
REST... Filter, Sorting & Pagination

#WISSENTEILEN
// FILTERING:
// List of paid orders (2015-12-20)
// Common Style
GET /orders?date=20151220&status=payed HTTP 1.1
REST
„filter“

#WISSENTEILEN
// FILTERING:
// Details of order 3 (product, date, ...)
// Facebook Style
GET /orders/3?fields=product,date,status HTTP/1.1
GET /orders/3?fields=item.product,date,status HTTP/1.1
// LinkedIn Style
GET /orders/3:(product, date, status) HTTP/1.1
REST
„filter“

#WISSENTEILEN
// FILTERING:
// Details of order 3
// without date, status
GET /orders/3?exclude=date,status HTTP/1.1
// predefined payload (compact = product, date, status)
GET /orders/3?style=compact HTTP/1.1
REST
„filter“
What is compact?

#WISSENTEILEN
// FILTERING:
// Details of order 3
// using PREFER HEADER for response payload definition
GET /orders/3 HTTP/1.1
Content-Type: application/json
Prefer: return=compact-format
HTTP 1.1 200 OK
Content-Type: application/json; charset=utf-8
Preference-Applied: return=compact-format
REST
„filter“

#WISSENTEILEN
// SORTING:
// orders sorted (date ↓ /item ↑)
// SQL alike style
GET /orders?sort=date+DESC,item+ASC HTTP/1.1
// Sort and asc/desc combination, ascending as default
GET /orders?sort=date,item&desc=date HTTP/1.1
// use prefix „-“ for descending, ascending as default
GET /orders?sort=-date,item HTTP/1.1
REST
„sorting“

#WISSENTEILEN
// FILTERING & SORTING:
// orders of „today“ sorted by ...
// long version
GET /orders?status=open
&date_from=20170510&date_to=20170510
&fields=product,status,time&sort=-time,product
// short and readable version
GET /orders/open_orders_of_today
GET /open_orders_of_today
REST
„filter&sort“

#WISSENTEILEN
// Pagination a.k.a. „Limiting“:
// return page 4 of orders
// Is page a query parameter?
GET /orders?page=4 HTTP/1.1
// Or is page a „virtual“ resource?
GET /orders/pages/4 HTTP/1.1
REST
„pagination“
„4“?
PREV? NEXT?
FIRST? LAST?

#WISSENTEILEN
// get “page 4“ and info about PREV/NEXT
GET /orders?offset=10&limit=5 HTTP/1.1
// Response with success code and link header for
// navigation purpose
HTTP/1.1. 200 OK
Link: <.../orders?offset=0&limit=5>; rel=„first“
<.../orders?offset=5&limit=5>; rel=„prev“,
<.../orders?offset=15&limit=5>; rel=„next“,
<.../orders?offset=40&limit=2>; rel=„last“
REST
„pagination“

#WISSENTEILEN
// get “page 4“ and info about PREV/NEXT
GET /orders?page=4&limit=5 HTTP/1.1
// Response with success code and link header for
// navigation purpose
HTTP/1.1. 200 OK
Link: <.../orders?page=1&limit=5>; rel=„first“
<.../orders?page=3&limit=5>; rel=„prev“,
<.../orders?page=5&limit=5>; rel=„next“,
<.../orders?page=8&limit=2>; rel=„last“
REST
„pagination“

#WISSENTEILEN
// FULL TEXT SEARCH:
// Fulltext search for coffee
// Global style via virtual resource
GET /searches?q=coffee HTTP/1.1 oder
// Scoped style
GET /orders/searches?q=coffee HTTP/1.1
GET /orders?q=coffee HTTP/1.1
REST
„search“
„GET vs.
POST
„GET vs.
POST

#WISSENTEILEN
// ADVANCED SEARCH:
// Coffee WITH milk for 2€
// Query for ...
GET /orders?type=coffee&ingredient=milk&price=2
REST
„search“
BTW: AND or OR or
AND/OR?

#WISSENTEILEN
// ADVANCED SEARCH:
// Coffee WITH milk for LESS THAN 2€
// Query for ...
GET /orders?query=type=coffee+ingredient=milk+price<=2
REST
„search“
Build your own
„Query Language“?

#WISSENTEILEN
// ADVANCED SEARCH:
// Coffee WITH milk or LESS THAN 2€
// RQL query ... (must possibly be encoded!)
GET /orders?query=
and(eq(type,coffee),
or(eq(ingredients,MILK),lt(price,2))
// RQL alternative query – FIQL (URI friendly) - ...
GET /orders?query=
type==coffee;(ingredients==MILK,price=lt=2)
REST
„search“

Use Standards
Standards promote efficiency, trust and safety
https://www.din.de/en/about-standards/use-standards

#WISSENTEILEN
Always remember: „The Web is your Friend“
• das Web bietet tolle Möglichkeiten zur „Skalierung“
• RESTful Service nutzen das Web bzw. HTTP
• Client (Web Browser, REST Client, ...)
• Proxy Caches („man in the middle cache“)
• Content Delivery Networks (CDNs)
Caching

#WISSENTEILEN
// Caching in REST:
// Expires-Header (HTTP 1.0)
HTTP/1.1 200 Ok
Expires: Mon, 24 SEP 2018 12:00:01 GMT
{
"id": "1",
"firstName": "Max",
"lastName": "Mustermann",
... ...
}
REST
„Cache“
„Hint, ok. Aber für
wen eigentlich?“

#WISSENTEILEN
CACHING
Cache-Control (HTTP 1.1)
• deutlich genauere Cache-Steuerung als bei Expires Header
• private, public
• no-cache
• no-store
• no-transform
• max-age, s-maxage

#WISSENTEILEN
// Caching in REST:
// Cache-Control (HTTP 1.1)
HTTP/1.1 200 Ok
Cache-Control: private, no-store, max-age=3600
{
"id": "1",
"firstName": "Max",
"lastName": "Mustermann",
...
}
REST
„Cache“
„Only client side
caching. Valid for
3600 sec. Must not
be stored on disc.“

#WISSENTEILEN
CACHING
Revalidation & Conditional GET (HTTP 1.1)
• Revalidation zur Prüfung, ob Cache-Daten wirklich invalide
• Server sendet speziellen Header zur Prüfung zurück
• Last-Modified
• Etag

#WISSENTEILEN
// Caching in REST:
// Revalidation & Conditional GET
// Cache-Control + Last-Modified Header HTTP 1.1
HTTP/1.1 200 Ok
Cache-Control: max-age=3600
Last-Modified: Wed, 10 MAI 2017 12:00:01 GMT
{
"id": "1",
...
}
REST
„Cache“

#WISSENTEILEN
// Caching in REST:
// Conditional GET after Timeout (max-age)
GET /products/123 HTTP/1.1
If-Modified-Since: Wed, 10 MAI 2017 12:00:01 GMT
REST
„Cache“
Modified since? No,
304 (Not Modified).
Yes, 200 (Ok) plus
Data.

#WISSENTEILEN
// Caching in REST:
// Cache-Control + eTag Header HTTP 1.1
HTTP/1.1 200 Ok
Cache-Control: max-age=3600
eTag: "1234567890987654321"
{
"id": "1",
...
}
REST
„Cache“

#WISSENTEILEN
// Caching in REST:
// Revalidation & Condition GET
// Conditional GET after Timeout (max-age)
GET /products/123 HTTP/1.1
If-None-Match: "1234567890987654321"
REST
„Cache“
Modified since? No,
304 (Not Modified).
Yes, 200 (Ok) plus
Data.

#WISSENTEILEN
// Optimistic Locking
// Conditional PUT
// Conditional PUT
PUT /customers/1234 HTTP/1.1
If-Match: "1234567890987654321"
REST
„Cache“
Modified in between?
No, 200 (OK).
Yes, 412
(Precondition Failed)

#WISSENTEILEN
// Optimistic Locking
// Conditional PUT
// PUT ohne Precondition
REST
„Cache“
Force Optimistic
Locking:
428 (Precondition
Required)

#WISSENTEILEN
REST ... Headers

#WISSENTEILEN
Headers
HTTP Header Parameter
• Meta Daten für Request / Response
• Accept: ich komme mit Format xyz klar
• Content-Type: ich sende dir Format xyz
• Location-Header: genauere/mehr Info zu „mir“ unter ...
• Link-Header: siehe auch unter ...
• Authorization*-Header: Auth Tokens, Basic Auth ...
• X-Custom-Header: ich habe da noch was für dich ...
{?}

#WISSENTEILEN
REST... Status Codes
(see also: http://www.restpatterns.org/HTTP_Status_Codes/)

#WISSENTEILEN
Pro Tipp: Use them!
• 1xx: Hold on ...
• 2xx: Here you go!
• 3xx: Go away!
• 4xx: You f#!?ed up!
• 5xx: I f#!?ed up!
(http://restlet.com/http-status-codes-map)
Facebook
„Always 200“
Anti-Pattern
HTTP Status Codes
(http://www.restpatterns.org/HTTP_Status_Codes)

#WISSENTEILEN
// HTTP Status Codes:
// signal that new order was created
// „Create new Resource“ of type order
POST /customers HTTP/1.1
[various other headers]
// Response with location header pointing to resource
HTTP/1.1. 201 Created
Location: http://…/customers/1234
REST
„Codes“

#WISSENTEILEN
// signal that some work is going on
// Trigger some async workload
POST /customers/
HTTP/1.1
// Response without payload, cause it‘s not yet calculated
HTTP/1.1. 202 Accepted
REST
„Codes“

#WISSENTEILEN
// signal that payload is empty
// DELETE customer with id 1234
DELETE /customers/1234 HTTP/1.1
// Customer successfully deleted. No content by purpose
HTTP/1.1. 204 No content
HTTP/1.1. 205 Reset content
REST
„Codes“

#WISSENTEILEN
// signal that payload is empty
// Retrieve all verified customers
GET /customers?status=verified HTTP/1.1
// There is no verified customer left.
HTTP/1.1. 204 No content
REST
„Codes“

#WISSENTEILEN
// signal that there is more payload
// GET all orders on „page“ two
GET /customers?page=4 HTTP/1.1
// Response with success code and links for navigation
HTTP/1.1. 206 Partial content
Link: <http://.../customers?page=1>; rel= „first“
<http://.../customers?page=3>; rel= „prev“,
...
REST
„Codes“

#WISSENTEILEN
// signal that could not find order
// Ask for customer with id 1234
GET /customers/1234 HTTP/1.1
// Could not find customer with id 1234
HTTP/1.1. 404 Not found
REST
„Codes“

#WISSENTEILEN
// signal that there is a limit problem
// Error Responses: Use them wisely
HTTP/1.1 429 To many request
HTTP/1.1 509 Bandwith limit exceeded
REST
„Codes“

#WISSENTEILEN
// Rate limit exceeded (e.g. Twitter)
HTTP/1.1 429 To many requests
{
"errors": [
{ "code": 88,
"message": "Rate limit exceeded" }
]
}
REST
„Codes“

#WISSENTEILEN
// Rate limit exceeded (e.g. Twitter)
HTTP/1.1 200 Ok
X-Rate-Limit-Limit: ... // rate limit ceiling
X-Rate-Limit-Remaining: ... // for the next 15 minutes
X-Rate-Limit-Reset: ... // in UTC epoch seconds
REST
„Codes“

#WISSENTEILEN
// signal that the payload is invalid
// Change customer with id 1234
// Some content is invald
HTTP/1.1. 400 Bad Request
REST
„Codes“

#WISSENTEILEN
// Bad request
// - Validation error with problem+json
HTTP/1.1 400 Bad request
Content-Type: application/problem+json
{
"type": "/problems/validation-error",
"title": "Your request parameters didn't validate.",
"status": 400,
"detail": "...",
"instance": "orders/1234"
}
REST
„Codes“

#WISSENTEILEN
// Bad request
// - Validation error with problem+json
HTTP/1.1 400 Bad request
{
"type": "/problems/validation-error",
"title": "Your request parameters didn't validate.",
...
"invalid-params": [
{ "path": "firstName",
"message": "firstName is mandatory" } ] }
Custom Extension for
Problem JSON
REST
„Codes“

#WISSENTEILEN
Manchmal kommt es anders, als man denk
• Code for Code: Status Code & Application Level Code
• Message for People: Für Logs, Ausgaben, ...
• Payload and Format: genormte Error-Payload Format
HTTP Status Codes

#WISSENTEILEN
// „Create new customer“.
POST /customers
// Is this allowed? Guess not. Is it?
POST /customers/1234
// „Change customer“. I‘am sure! But wait ...“
PUT /customers/1234
// „Change customer“, too? Isn‘t it?
REST
„method“

#WISSENTEILEN
// Which patch should be used
HTTP/1.1 415 Unsupported Media Type
{
"type": "/problems/unsupported-media-type",
"detail": "supported media types are
application/merge-patch+json or
application/json-patch+json",
}
REST
„Payload“

#WISSENTEILEN
// HTTP PATCH:
// json/merge-patch+json
POST /customers
{
"customerNumber": "1234",
"name": {
"firstName": "Max",
"lastName": "Mustermann"
},
"email": "max.mustermann@beispiel.de"
}
REST
„Payload“

#WISSENTEILEN
// HTTP PATCH:
// json/merge-patch+json
// leave customer number and first name unchanged
// change last name, remove email
Content-Type: application/merge-patch+json
{
"name": {
"lastName": "Muster"
},
"email": null
}
REST
„Payload“

#WISSENTEILEN
// HTTP PATCH:
// json/json-patch+json
PATCH /customers/
Content-Type: application/json-patch+json
[
{ "op": "remove", "path": "/1234/email" },
{ "op": "replace",
"path": "/1234/name/last", "value": "Muster" },
{ "op": "add",
"path": "/1234/name/additional", "value": "Thomas" },
{ "op": "move", "from": "/1234", "path": "/1235" },
]
REST
„Payload“

#WISSENTEILEN
„Leonard Richardson proposed a
classification for services on the Web.
Leonard’s model promotes three levels of
service maturity based on a service’s
support for URIs, HTTP, and hypermedia!“
(Quelle: „REST in Practice“)

#WISSENTEILEN
RICHARTSON MATURITY MODEL
0
1
2
3 Hypermedia
URI
HTTP

Level 0
• a.k.a. „Swamp of PoX“:
• HTTP als Transportsystem
• „RPC“-Style
• eine URI
• eine HTTP Methode (meist POST)
• Parameter und Rückgabe als Payload (XML/JSON/TEXT)

Level 1
• Aufbrechen des monolithischen Endpoints aus Level 0 in unterschiedliche
Ressourcen (a.k.a. Nomen), die gezielt angesprochen werden können.

Level 1
• a.k.a. „Resources“
• Individuelle Ressourcen statt Service Endpoint
• mehrere URIs
• ein oder zwei HTTP Methode (meist POST/GET)
• Parameter als Query-Parameter oder Payload
• Rückgabe als Payload (XML/JSON/TEXT)

Level 2
• Einführen verschiedener „Verben“, um gleiche Situationen mit den selben
Mechanismen behandeln zu können und so unnötige Varianten zu vermeiden.

Level 2
• a.k.a. „Verbs“
• „passende“ HTTP Methoden statt nur POST & GET
• mehrere URIs
• mehrere HTTP Methoden
• Rückgabe als Payload & Status Codes

Level 3
• Einführen von „Auffindbarkeit“, um so einen Mechanismus anzubieten, der das
Protokoll selbsterklärend(er) macht.

Level 3
• a.k.a. „Hypermedia“
• selbsterklärendes System
• nur eine Einstiegs-URI bekannt
• keine weiteren festen URIs
• Rückgabe als Liste von neuen „Möglichkeiten“

#WISSENTEILEN
„If the engine of application state (and
hence the API) is not driven by hypertext,
then it cannot be RESTful and cannot be a
REST API. Period. Is there some broken
manual somewhere that needs to be
fixed?“
Roy Fielding

#WISSENTEILEN
„A REST API should be entered with no
prior knowledge beyond the initial URI ...
From that point on, all application state
transitions must be driven by the client
selection of server-provides choices ...“
Roy Fielding

/orders/...
POST /orders { order payload }
http/1.1 201 Created
Location: ...
Link: cancel operation
update operation
delete operation
pay operation
C
O
N
S
U
M
E
R
O
R
D
E
R
S

/orders/...
/payments/...
http/1.1 201 Created
Location: ...
Link: http://<status operation>
http://<update operation>
http://<delete operation>
http://<pay operation>
GET
PUT
DELETE
POST
O
R
D
E
R
P
A
Y

#WISSENTEILEN
REST
„Hateoas“ v1
// Richardson Maturity Model:
// Hypermedia as the engine
// of application state
POST /orders/ HTTP/1.1
{ ... payload of order to create ... }
HTTP/1.1. 201 Created
Location: http://restbucks.com/api/orders/1234
Link: <.../orders/1234>; rel=„cancel“
<.../orders/1234>; rel=„update“,
<.../orders/1234>; rel=„delete“,
<.../payment/1234>; rel=„pay“

#WISSENTEILEN
// Aber wie bilde ich Relationen ab?
// the „naive“ way
// all customers
{
[
{ "id":"001", "for":"arne", ..., "addresses":[ ...] },
{ "id":"002", "for":"lars", ..., "addresses":[ ...] },
...
]
}
REST
„relation“

#WISSENTEILEN
// the „naive“ way
// all customers
{
[
{ "id":"001", "for":"arne", ..., "addresses":[ ...] },
{ "id":"002", "for":"lars", ..., "addresses":[ ...] },
...
]
}
REST
„relation“
Benötige ich die Info hier wirklich?

#WISSENTEILEN
// the „linked“ way
// all customers
{
[
{ "id":"001", "for":"arne", ..., "address_refs":[...]},
{ "id":"002", "for":"lars", ..., "address_refs":[...] },
...
]
}
REST
„relation“
https://..../customers/002/addresses/1
https://..../customers/002/addresses/2
Benötige ich weitere Infos?

#WISSENTEILEN
// all customers
{
[
{ "id":"001",
"for":"lars",
...,
"addresses_refs":[...],
"addresses_count" : 2
]
}
REST
„relation“

#WISSENTEILEN
// all customers
{
[
{ "id":"001",
"for":"lars",
"for_ref ": "http://.../customers/12",
...,
"addresses_refs":[...],
"addresses_count" : 2
]}
REST
„relation“

#WISSENTEILEN
// all customers
{
[
{ "id":"001", "for":"arne", ..., "address":[
{
"href": "http://.../customers/001/addresses/1"
}
]},
...
]
}
REST
„relation“
Welche Syntax hilft dem Consumer?

#WISSENTEILEN
Content-Type: application/hal+json
{
"_embedded": {
"customers": [{
"_links": {
"self": { "href": "/customers/001“ }, …
},
"name": "Arne Limburg", …
}, …]},
"_links": {
"next": …
"find": {"href": "/customers{?tags}", "templated": true}
}, …
}
REST
„relation“

#WISSENTEILEN
DOCUMENTATION
OpenAPI Specification (OAS)
Design mit Swagger Editor Build mit Swagger Codegen Dokumentiere mit Swagger-UI

#WISSENTEILEN
// openapi.json
// JSON-Schema / OpenAPI Example
"post" : {
"parameters" : [ {
"in" : "body",
"name" : "body",
"description" : "new customer",
"required" : true,
"schema" : {
"$ref" : "#/definitions/Customer"
}
} ]
}
REST
„OpenAPI“

#WISSENTEILEN
// openapi.json (JSON Schema)
"definitions" : {
"CustomerResourceType" : {
"type" : "object",
"required" : [ "firstName", "lastName”, … ],
"properties" : {
"firstName" : {
"type" : "string",
"minLength" : 1,
"maxLength" : 30,
"pattern" : "..."
}
}
REST
„OpenAPI“

MICROSERVICES ARCHITEKTUR
Address Validation Service
Delivery Service
Customer Service
Billing Service

Tolerant Reader Pattern
Tolerant gegenüber unbekannten Feldern
Umgang mit x-extensible-enum
http://zalando.github.io/restful-api-guidelines

EXKURS X-EXTENSIBLE-ENUM
Beispiel
address_type:
type: string
x-extensible-enum:
- private
- business

Tolerant Reader Pattern
Tolerant gegenüber unbekannten Feldern
Umgang mit x-extensible-enum
Tolerant gegenüber unbekannten Statuscodes
HTTP Status 301 folgen

TOLERANT READER PATTERN
http://www.example.com/addresses/42
àLiefert Addresse
{
street: {
"name": "Poststraße",
"number": "1",
},
"city": "26122 Oldenburg"
}

Attribut hinzufügen
{
street: {
"number": "1",
"additionalAdressLine": "2. Obergeschoss"
},
}

Server schickt
{
street: {
"number": "1",
"additionalAdressLine":
"2. Obergeschoss"
}...
}
Client erwartet
{
street: {
"number": "1",
}...
}

Attribut-Umbenennung
{
street: {
"streetName": "Poststraße",
"number": "1",
"houseNumber": "1",
},
}

àAbwärtskompatible Änderungen: Umbenennen durch Kopieren
{
street: {
"number": "1",
"houseNumber": "1",
},
}

Und was ist, wenn der Client kein
Tolerant Reader ist?

PROJEKTIONEN
// Client kann entscheiden, welche Felder er bekommen möchte
// Facebook Style
GET /addresses/3?fields=street,city
GET /addresses/3?fields=street.name,street.number,city
// LinkedIn Style
GET /addresses/3?fields=street:(name,number),city

OK, so soll sich
der Client verhalten.
Aber was ist mit dem Server?

Photo by Irene Fertik, USC News Service. Copyright 1994, USC.
„Be conservative in what you do,
Be liberal in what you accept
from others“
RFC 793, Robustness Principal (John Postel)

Es darf nichts entfernt werden
Keine Veränderung von Verarbeitungsregel
Optionales darf nie Required werden
Alles was hinzugefügt wird, muss optional sein

MAGNANIMOUS WRITER PATTERN
Server schickt
{
street: {
"number": "1",
"houseNumber": "1“
}...
}
Client erwartet
{
street: {
"number": "1",
}...
}
http://tenderware.blogspot.de/2011/05/magnanimous-writer.html

Server schickt
{
street: {
"number": "1",
}...
}
Client erwartet
{
street: {
"houseNumber": "1",
}...
}

Server erwartet
PUT http://www.example.com/addresses/42
Client schickt
{
street: {
"number": "1",
}...
}

Client schickt
{
street: {
"number": "1",
}...
}
Server erwartet
{
street: {
"number": "1",
}...
}
oder
oder

Client schickt
{
street: {
"houseNumber": "1",
}...
}
Server erwartet
{
street: {
"number": "1",
}...
}
oder
oder

MERGE PATCH UND NULL VALUES
PATCH /addresses/42 HTTP/1.1
Content-Type: application/merge-patch+json
Client schickt
{
street: {
"name": null,
}...
}
https://tools.ietf.org/html/rfc7396

ABWÄRTSKOMPATIBILITÄT
àAbwärtskompatible Änderungen: Umbenennen durch Kopieren
{
street: {
"number": "1",
"houseNumber": "1",
},
}
Geht da noch mehr?

àZusammenführen und Teilen von Attributen
{
street: {
...
"houseNumber": "1",
"addressLine1": "Poststraße 1",
}
...
}

àHerausforderungen: Zusammenführen von Attributen
{
street: {
...
"houseNumber": "1",
}
...
}

àHerausforderungen: Teilen von Attributen
{
street: {
...
}
"city": "26122 Oldenburg",
"zipCode": "26122",
"cityName": "Oldenburg"
}

àHerausforderungen: Ebene von Attributen ändern
{
street: {
...
"addressLine1": "Poststraße 1"
}
...
}

{
...
"zipCode": "26122",
"cityName": "Oldenburg",
"location": {
"zipCode": "26122",
}
}

{
...
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
Bei jeder Modelländerung muss
eine Migrationsstrategie
einbezogen werden!

{
street: {
"number": "1",
"houseNumber": "1",
"addressLine1": "Post... 1",
"addressLine2": ""
}
"addressLine2": "",
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
http://www.example.com/v1/addresses/42
àBisher nur abwärtskompatible Änderungen

{
street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
}
"addressLine2": "",
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
àViele Attribute deprecated

Wie kann ich Attribute entfernen?

Don‘t ever break your
Client

Incompatible Change
vs. Breaking Change

CONSUMER-DRIVEN CONTRACT TEST
Consumer
Contract
Consumer Provider
Consumer
Tests
Provider
Tests

PIPELINE TO DEPLOY TO STAGE
Execute
Own
Provider
Tests
Generate
Consumer
Contract
Execute
Depending
Provider
Tests
Deploy
to
Stage

PIPELINE TO DEPLOY TO STAGE
Execute
Own
Provider
Tests
Generate
Consumer
Contract
Execute
Depending
Provider
Tests
Deploy
to
Stage
Achtung:
Abwärtskompatibilität ist
trotzdem notwendig!

BREAKING CHANGE VOM PROVIDER
Execute
Own
Provider
Tests
Generate
Consumer
Contract
Execute
Depending
Provider
Tests
Deploy
to
Stage

BREAKING CHANGE VOM CONSUMER
Execute
Own
Provider
Tests
Generate
Consumer
Contract
Execute
Depending
Provider
Tests
Deploy
to
Stage

Und wenn ich meine Consumer
nicht kenne?

VERSIONSSPRUNG
{
street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
}
"addressLine2": "",
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
àBisher nur abwärtskompatible Änderungen

INKOMPATIBLE ÄNDERUNG
àVersionssprung
{
"addressLine2": "",
"location": {
"zipCode": "26122",
}
}

Version 2.0
ist nur inkompatibel zu 1.0!
Version 2.0 ist identisch zu 1.x!
Das erleichtert das Mapping
zwischen den Versionen!

Ein solcher Versionssprung ist
nicht anforderungsgetrieben,
sondern viel besser und
langfristiger planbar

Wenn eine neue Version
nicht auf die alte abbildbar ist,
ist es keine neue Version,
sondern eine neue Schnittstelle!

• Über URL-Pfad
/v2/addresses
• Über Query-Parameter
/addresses?version=v2
• Über Version-Header
X-Api-Version: v2
• Über Version-Attribut am Media-Type
application/xml;version=v2
• Über Media-Type
application/vnd.de.openknowledge+v2+json
ERMITTELN DER VERSION

Schnittstelle Schnittstelle
{ street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
}
"zipCode": "26122",
"addressLine2": "",
"location": {
"zipCode": "26122",
}
}
{
"addressLine2": "“,
"location": {
"zipCode": "26122",
}
}
V1 V2-SNAPSHOT

{ street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
},
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
{
"addressLine2": "",
"location": {
"zipCode": "26122",
}
}
V1 V2-SNAPSHOT

AUTOMATISIERTES MAPPING
{ "street": {
"number": "1",
},
}
{
"street": {
"number": "1"
},
}
V1 V2-SNAPSHOT

WEITERENTWICKLUNG
{ "street": {
"number": "1",
"houseNumber": "1",
},
}
{
"street": {
"houseNumber": "1"
},
}
V1 V2-SNAPSHOT

WEITERENTWICKLUNG
{ "street": {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
},
}
{
"street": {
"addressLine1": "Post… 1",
"addressLine2": ""
},
}
V1 V2-SNAPSHOT

WEITERENTWICKLUNG
{ "street": {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
},
"addressLine2": "",
"zipCode": "26122",
}
{
"addressLine2": "",
"zipCode": "26122",
}
V1 V2-SNAPSHOT

WEITERENTWICKLUNG
{ "street": {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
},
"addressLine2": "",
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
{
"addressLine2": "",
"location": {
"zipCode": "26122",
}
}
V1 V2-SNAPSHOT

{ street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
},
"zipCode": "26122",
"location": {
"zipCode": "26122",
}
}
{
"addressLine2": "",
"location": {
"zipCode": "26122",
},
"city": {
"zipCode": "26122",
}
}
V1 V2-SNAPSHOT

Schnittstelle
Schnittstelle
{ street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
}
...
}
{
"addressLine2": "",
"location": {
"zipCode": "26122",
}
}
V1 V3-SNAPSHOT
Schnittstelle
{ "addressLine1": "Poststraße 1",
"location": {
"zipCode": "26122",
}
}
V2

Schnittstelle
Schnittstelle
{ street: {
"number": "1",
"houseNumber": "1",
"addressLine2": ""
}
...
}
{
"addressLine2": "",
"city": {
"zipCode": "26122",
}
}
V1 V3-SNAPSHOT
Schnittstelle
{ "addressLine1": "Poststraße 1",
"location": {
"zipCode": "26122",
},
"city": {
"zipCode": "26122",
}} V2

KONTAKT
ARNE LIMBURG,
ENTERPRISE ARCHITECT
arne.limburg@openknowledge.de
+49 (0)441 40820
OFFENKUNDIGGUT

Consumer-centric API Design

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Ähnlich wie Consumer-centric API Design

Ähnlich wie Consumer-centric API Design (20)

Mehr von OPEN KNOWLEDGE GmbH

Mehr von OPEN KNOWLEDGE GmbH (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Consumer-centric API Design