Das Dokument behandelt die Herausforderungen und Kritiken an REST-Architekturen, inklusive technischer Komplexität und Mängel bei Hypermedia-Clients. Es vergleicht REST mit Alternativen wie gRPC, JSON-RPC und GraphQL und hebt hervor, dass das API-Design nicht einfach ist und oft eine starke Abhängigkeit von spezifischen Standards erfordert. Abschließend wird festgestellt, dass REST zwar ideal für öffentliche APIs ist, aber es auch mehrere Alternativen gibt, die in bestimmten Szenarien vorteilhafter sein könnten.

1. REST: Versprechen,
Wirklichkeit & die
Alternativen GraphQL,
gRPC, JSON RPC...
Version 1.2 vom 17.4.2017
Thomas Bayer
bayer@predic8.de
@thomasub

2. REST
#1 ist zu technisch
#2 ist kein Standard
#3 ist datengetrieben
#4 Design ist kompliziert
#5 fehlen Hypermedia Clients
#6 wird von Swagger bedroht!

3. Server
Remote Procedure Call
Runtime
Client
Product
Service
Stub
createProduct( mango)
Eigener Code
Eigener Code
!= REST
Scheinbar direkter
Aufruf

4. Funktion
ParameterService
productService.create( mango);
Remote == Lokal

5. Server
Produkt
Service
Client
Produkt
Service
Stub
.proto
GRPC2JAVA
Problem: Build ist komplex und erfordert Know-How

6. Server
REST
GET /produkte/65
/produkte/64
/produkte/65
/produkte/66
Client
HTTP Client
Repräsentation
{ name:
... }
Kopie!
Ressource
GetMethod method = new GetMethod("http://api.predic8.de/shop/products/65");
int sc = client.executeMethod(method);
if (sc != HttpStatus.SC_OK) {
...
}
byte[] responseBody = method.getResponseBody();
200 OK
• Kein Build
• Skripting ist möglich

7. Quelle: https://trends.google.de/trends/explore?date=all&q=%2Fm%2F03nsxd,%2Fm%2F0315s4
SOA & REST Hype Cycle

8. Quelle: https://trends.google.de/trends/explore?date=all&q=%2Fm%2F03nsxd,%2Fm%2F0315s4
SOA & REST Hype Cycle
REST Ressource!

9. REST
#1 ist zu technisch
#2 ist kein Standard
#3 ist datengetrieben
#4 Design ist kompliziert
#5 fehlen Hypermedia Clients
#6 wird von Swagger bedroht!

10. Die Bibel
HTTP Spezifikationen
sind verbindlich

11. HTTP/1.1 201 Created
Content-Type: application/json
Location: /shop/products/96
{
"name": "Pears",
"price": 1.78,
"self_uri": "/shop/products/96"
}
POST /shop/products/ HTTP/1.1
Content-Type: application/json
{
"name":"Pears",
"price":1.78
}

12. RFC 7231
3.1.4.2. Content-Location
HTTP/1.1 201 Created
Content-Type: application/json
Location: /shop/products/96
Content-Location: /shop/products/96
{
"name": "Pears",
"price": 1.78,
"self_uri": "/shop/products/96"
}
POST /shop/products/ HTTP/1.1
Content-Type: application/json
{
"name":"Pears",
"price":1.78
}

13. Quellen: https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf
https://de.wikipedia.org/wiki/Roy_Fielding#/media/File:Roy_Fielding.jpg
Wichtige Schrift für REST
Fans! Geniales Papier über
die Architektur des Webs,
aber nichts Konkretes zu
REST API Design.
Fielding Dissertation

14. According to Fielding:
PUT vs. POST in REST auf Stackoverflow
Quelle: https://stackoverflow.com/questions/630453/put-vs-post-in-rest

15. Guidelines
• Whitehouse
• Twitter
• Haufe Lexware
• ...

16. REST
#1 ist zu technisch
#2 ist kein Standard
#3 ist datengetrieben
#4 ist kompliziert
#5 fehlen Hypermedia Clients
#6 wird von Swagger bedroht!

17. C POST /products/
R GET /products/65
U PUT /products/65
D DELETE /products/65

18. storniereBestellung( 74)

19. DELETE /bestellung/74

20. PATCH /bestellung/74 {
“status“: “storniert“
}

21. PUT /bestellung/74/storno

22. /machines/46

23. PUT /machines/46/stop
PUT /machines/46/start

24. /rechnungen/
/rechnungen/{rid}
/positionen/
/positionen/{pid}

25. /rechnungen/
/rechnungen/{rid}
/rechnungen/{rid}/positionen/
/rechnungen/{rid}/positionen/{pid}

26. REST ohne Hypermedia ist CRUD over HTTP!

27. DB
Service
API
Client
Logik
Logik
Logik wandet
zum Client
Logik ist Seiteneffekt
einer Datenänderung
Zum wenig
Abstraktion
Innere Struktur
wird offen gelegt

28. REST
#1 ist zu technisch
#2 ist kein Standard
#3 ist datengetrieben
#4 Design ist kompliziert
#5 fehlen Hypermedia Clients
#6 wird von Swagger bedroht!

29. GET /products
oder
GET /products/
?

30. POST /produkte/
PUT /produkte/65
PATCH /produkte/65
Resource GET POST PUT DELETE
/articles/ List aller Artikel 201 Created
Neuer Artikel
erzeugen*
Location
Header setzen!
400 Bad
Request
Alle Artikel
löschen
/articles/7 Details zu
einem Artikel
400 Bad
Request
Artikel
erzeugen* oder
ändern
Artikel löschen
?

31. Subressoucen
/products/11/photo
/kunden/65/vertraege/
/vendors/32/products/
/kunden/65/vertraege/6/policy/24
?

32. /shop/products/65
/shop/products/65?limit=10
/shop/products;limit=10/
{ “Limit“: 10 }
Parameter
?Limit: 10

33. ?Quelle: https://httpstatusdogs.com/

34. Prozesse &
Nicht-Ressource Anfragen
 Ressourcen passen irgendwie nicht richtig oder sind uninteressant
 Beispiele
 Errechnen
 Umwandeln
 Prozess als Ressource oft umständlich
/order/4/actions/cancel
/antrag/4354/freigabe
/calculator/compute

35. REST Design Probleme
 Mehrere Lösungen für ein Problem
 REST ist nicht einfach, wenn die Aufgaben größer werden
 Styleguide ist notwenig
 Auswahl & Erstellung sind schwer
 Es gibt keinen perfekten Styleguide
 Auswirkung vieler Designentscheidungen nicht sofort erkennbar!
 Viel Interpretation und Kreativität ist gefordert
 Man beschäftigt sich mehr mit der Auslegung von REST als mit der
Fachlichkeit
Welches REST API hat ein gutes Design?

36. API Design: The Musical
Quelle: https://events.drupal.org/losangeles2015/sessions/api-design-musical
Play

37. Automatisierte Design Tests
swagger-analyzer.com

38. REST
#1 ist zu technisch
#2 ist kein Standard
#3 ist datengetrieben
#4 ist kompliziert
#5 fehlen Hypermedia Clients
#6 wird von Swagger bedroht!

39. {
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}
https://api.predic8.de/shop/products/

40. {
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo",
}
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}
https://api.predic8.de/shop/products/

41. {
"name": "Pineapples",
"price": 3.55,
"photo_url": "https://api.predic8.de//shop/products/33/photo"
}
{
"products": [
{
"name": "Pineapples",
"product_url": "https://api.predic8.de/shop/products/33“
}
...
]
}
https://api.predic8.de/shop/

42. const traverson = require('traverson');
traverson
.from('https://api.predic8.de/shop/products/33')
.json()
.follow('vendor_url')
.getResource((err, json) => {
console.log("Hersteller: " + json.name)
});
https://github.com/traverson/traverson
Traverson Hypermedia Client for Node

43. Vertrag =Repräsentationen

44. Vertrag =Repräsentationen
URIs sind nicht Bestandteil
des Vertrages!

45. Hypermedia ist cool!

46. Wer verwendet Hypermedia?

47. ... und auf dem Client?

48. Client sendet Link in einer Repräsentation
POST /shop/products/ HTTP/1.1
Content-Type: application/json
{
"name": "Pears",
"price": 1.78,
"vendor_url": "/shop/vendors/32"
}
HTTP/1.1 201 Created
Content-Type: application/json
Location: /shop/products/97
{
"name": "Pears",
"price":1.78,
"vendor_url":"/shop/vendors/32",
"product_url":"/shop/products/97"
}

54. Hypermedia Probleme
 Design ist aufwendig
 Dokumentewerdenlang undhäßlich
 VieleFormate, Best Practice, ...
 Clientverschmäht Hypermedia!

55. REST
#1 ist zu technisch
#2 ist kein Standard
#3 ist datengetrieben
#4 ist kompliziert
#5 fehlen Hypermedia Clients
#6 wird von Swagger bedroht!

56. Id angeben anstatt Link
verfolgen.
URI Template

57. Wer URIs dokumentiert macht RPC!
Fixe URIs führen zu starker Kopllung!
Mediatypes erfordern Dokumentation
Fielding, Kapitel 5!

58. Contract First mit Swagger
Swagger
mvn deploy
MVN
client.jar
Dependency
call
Projekt wird nur
gebaut. Kein
eigener Code
notwendig.
Code
Generation
Server Stub wird um
die Implementierung
erweitert
Client

61. • Das Remoting ist komplett
verborgen
• RPC sieht genauso aus

64. Erzeugte Methode
erfordert Id

65. Regex macht aus
URI id für Template

66. In Zahl umwandeln

67. /produkt/{pid}
+ 65
= /produkt/65
URI Templates sind nicht REST!

68.  Hypermedia und Swagger passen nicht zusammen!
 Swagger => RPC Stil
+
Swagger kills Hypermedia
• Swagger hat Vorteile
• HATEOAS hat Vorteile
• Swagger + HATEOAS gleichzeitig
• => Nachteil

69. REST ist nur (gutes) REST mit Hypermedia
Keiner macht Hypermedia => REST?

70. REST Alternativen
JSON RPC
GraphQL
GRPC

71. JSON RPC über HTTP
POST / HTTP/1.1
Content-Type: application/json;
{
"method": “get-preis",
"jsonrpc":“ 2.0",
"params": {
"name": "Mango"
},
"id":null
}

72. JSON RPC Server
var jayson = require('jayson');
const server = jayson.server({
createProduct: ( product, cb) => {
console.log("Creating " + product.name)
cb( null, { "success": true});
}
});
server.http().listen(8080);

73. REST Alternativen
JSON RPC
GraphQL
GRPC

74. Aufgabe: App mit Liste der Produkte
Mango
Kiwi
Apfel
Banane
Pfirsich

76. Client Server
t
Zeitverhalten entfernter Aufrufe

77. Preis?
Mango 1,99
Kiwi 2,10
Apfel 1,99
Banane 0,79
Pfirsich 1,29

78. Preis?

79. Client API
/shop/products/
/shop/products/3
/shop/products/10
/shop/products/33
Eine Abfrage der
Container Ressource
n-Abfragen für alle
Produkte der Liste
N + 1 Calls!
Chatty

80. Client Server
t
Zeitverhalten entfernter Aufrufe
/products/
/products/3
/products/7

81. Chunky or Chatty?
 Over Fetching
 Mehr Daten als notwendig werden übertragen
 => Chunky
 Under Fetching
 Nicht genug Daten werden übertragen
• => Subressourcen oder Relationen müssen verfolgt werden
• => Chatty
Quelle:
• https://pixabay.com/de/blabla-tafel-belanglosigkeit-1432922/
• https://pixabay.com/de/katze-dunkel-kaffee-faul-liegen-1351612/

82. /products/65?expand=vendor&fields=name,price
{
"name": "Pineapples",
"price": 3.55,
"vendor": {
“name“: “Exotic Fruits“
}
}

83. /products/65?expand=vendor&fields=name,price
{
"name": "Pineapples",
"price": 3.55,
"vendor": {
“name“: “Exotic Fruits“
}
}
Query Language

84. expand=vendor&fields=name,price
Genügt die Query Language?

85. GraphQL

86. REST Alternativen
JSON RPC
GraphQL
GRPC

87. GRPC
 RPC Framework
 Basiert auf Google Protocol Buffers
 Verwendet IDL
 Protocol Buffers als Message Format
• JSON ist auch möglich
 Art neues CORBA
 HTTP/2 Transport
 Geeignet für Mobile
 Google stellt auf GRPC für Microservices um
 Features
 Streaming
 Sprachunterstützung
 Android, C++,C#, Go, Java, Node, Objective-C, PHP, Python, Ruby
 Quelle
 https://grpc.io

88. Java ServerObjective-C Client
Stub
get(id)
gRPC Server
get(id)
MyCode
MyCode
protoc
.proto
service ProductManager {
rpc get(int32) returns (Product) {}
}
protobuf

89. Interface Definition Language
package fruitshop;
service ProductService {
rpc Create (CreateProductRequest) returns (CreateProductResponse) {}
}
message CreateProductRequest {
string name = 1;
float price = 2;
}
message CreateProductResponse {
}

90. ServiceImpl
class ProductServiceImpl extends ProductServiceGrpc.ProductServiceImplBase {
@Override
public void create(CreateProductRequest req,
StreamObserver<CreateProductResponse> resObserv) {
System.out.println("request = " + req);
CreateProductResponse reply = CreateProductResponse.newBuilder().build();
resObserv.onNext(reply);
resObserv.onCompleted();
}
}

91. Server
Server server = ServerBuilder.forPort(5000)
.addService(new ProductServiceImpl())
.build()
.start();
server.awaitTermination();

92. Client
ManagedChannel channel =
ManagedChannelBuilder.forAddress("localhost", 5000)
.usePlaintext(true)
.build();
ProductServiceBlockingStub stub = newBlockingStub(channel);
CreateProductRequest req = CreateProductRequest
.newBuilder()
.setName("Mango")
.setPrice(1.90f)
.build();
stub.create(req);

94. „The REST interface is designed to be efficient for large-
grain hypermedia data transfer, optimizing for the
common case of the Web, but resulting in an interface that
is not optimal for other forms of architectural
interaction.“
Quelle: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
Fielding in 5.1.5 Uniform Interface

95. Anwendung?
Public APIs Mobile Komplexe APIs
REST ++ - -
JSON RPC ++ + -
GRPC - + ++
GraphQL - ++ +
?

96. Fazit
 REST ist ideal für Public APIs
 REST kann jeder!
REST Design ist schwer
 Es gibt Alternativen zu REST
Messaging
RPC
Query Languages

97. REST is dead.
Long live REST!

98. @thomasub
bayer@predic8.de

99. Quellen
 Architectural Styles and the Design of Network-based Software
Architectures, Roy Thomas Fielding
 https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
 RFC 7230, Hypertext Transfer Protocol (HTTP/1.1): Message
Syntax and Routing
 https://tools.ietf.org/html/rfc7230
 RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and
Content
 https://tools.ietf.org/html/rfc7231
 White House Web API Standards
 https://github.com/WhiteHouse/api-standards
 Haufe API Style Guide
 https://github.com/Haufe-Lexware/api-style-guide
 RESTful APIs, the big lie, Michael S. Mikowski
 https://mmikowski.github.io/the_lie/
 Status Dogs
 https://httpstatusdogs.com/