Das Dokument behandelt die Prinzipien und Eigenschaften von REST (Representational State Transfer) als Architektur für verteilte Systeme im Web, einschließlich der Client-Server-Trennung, statusloser Kommunikation und der Verwendung von URIs zur Identifizierung von Ressourcen. Es wird erläutert, warum REST eine vorteilhaftere Alternative zu WS*-Services ist, insbesondere hinsichtlich Interoperabilität, Flexibilität und Benutzerfreundlichkeit. Zudem werden Best Practices für die Implementierung von RESTful Services beschrieben, darunter die Verwendung von Standard-HTTP-Methoden und die Notwendigkeit von Hypermedia.

1. Conference 2013. Innsbruck.
REST. Namics.
Daniel Scherrer. Senior Software Architect.
August 2013

2. Namics.
Agenda.
 Was ist REST / Rest-Prinzipien
 Warum Rest und nicht WS*?
 Good-Practices
 Richtige Abstraktionsstufen wählen
 Das richtige Mass finden (Hypermedia, Yoga, usw.)
 Versionierung
 Authentifzierungsvarianten
 Spezifikation eines Services
 Entwicklungsvorgehen
 Tools
30.04.2015 Denken. Präsentieren. Umsetzen.2

3. Namics.
Was ist REST ?

4. Namics.
Die Welt vor REST
30.04.2015 4 Denken. Präsentieren. Umsetzen.

5. Namics.
Die Welt vor REST
30.04.2015 5 Denken. Präsentieren. Umsetzen.

6. Namics.
Die Welt vor REST
 Viele verschiedene «Standards»
 RMI, SOAP, Corba, DCE, DCOM, …
 Von vielen verschiedenen Organisationen
 Sun, Microsoft, IBM, OASIS, OMG
 Mit vielen Problemen
 Schlechte interoperabilität
 Das Rad wurde immer wieder neu erfunden
 Vendor «lock-in»
30.04.2015 6 Denken. Präsentieren. Umsetzen.

7. Namics.
… dann kam REST !
“Representational State Transfer (REST) is a style of software
architecture for distributed systems such as the World Wide
Web”
wikipedia
30.04.2015 7 Denken. Präsentieren. Umsetzen.

8. Namics.
REST ist da! Weg mit dem Rest!
30.04.2015 8 Denken. Präsentieren. Umsetzen.

9. Namics.
Eigenschaften von REST
 Client / Server
 Trennung von Client- und Server-Logik
 Statuslose Kommunikation
 Jeder Request beinhaltet alle benötigten Informationen
 Cache’bar
 Clients können antworten «zwischenspeichern» – insofern dies erlaubt
wurde
 Uniform Interface
 Einheitliche Schnittstelle zw. Client & Server (Selbstbeschreibend)
 Layered System
 Erlaubt den Einsatz von Schichtenarchitekturen inkl. Load-Balancers,
Proxies und Firewalls
30.04.2015 Denken. Präsentieren. Umsetzen.9

10. Namics.
Eigenschaften von REST
 Client / Server
 Trennung von Client- und Server-Logik
30.04.2015 Denken. Präsentieren. Umsetzen.10
Processing
on servers

11. Namics.
Eigenschaften von REST
 Statuslose Kommunikation
 Jeder Request beinhaltet alle benötigten Informationen
 Ermöglicht hohe Skalierung
30.04.2015 Denken. Präsentieren. Umsetzen.11
Wer bin ich
Was will ich
Wie will ich es

12. Namics.
Eigenschaften von REST
 Cache’bar
 Clients können antworten «zwischenspeichern» – insofern dies erlaubt
wurde
30.04.2015 Denken. Präsentieren. Umsetzen.12
Gültigkeit
von 3 Stunden,
Darling!

13. Namics.
Eigenschaften von REST
 Uniform Interface
 Einheitliche Schnittstelle zw. Client & Server (Selbstbeschreibend)
30.04.2015 Denken. Präsentieren. Umsetzen.13
GET
PUT
POST
DELETE
HEAD
OPTIONS
/conference/tracks/6

14. Namics.
Eigenschaften von REST
 Layered System
 Erlaubt den Einsatz von Schichtenarchitekturen inkl. Load-Balancers,
Proxies und Firewalls
30.04.2015 Denken. Präsentieren. Umsetzen.14

15. Namics.
Eigenschaften von REST
 Layered System
 Erlaubt den Einsatz von Schichtenarchitekturen inkl. Load-Balancers,
Proxies und Firewalls
30.04.2015 Denken. Präsentieren. Umsetzen.15

16. Namics.
ROA
 Im Fokus der «Dinge»
30.04.2015 16 Denken. Präsentieren. Umsetzen.

17. Namics.
Grundprinzipien
 Gebe jedem «Ding» eine ID (URI)
 Benutze Hyperlinks als Verknüpfung der «Dinge»
 Benutze Standard-Methoden
 «Dinge» haben mehrere Repräsentationen
 Kommuniziere statuslos
30.04.2015 17 Denken. Präsentieren. Umsetzen.

18. Namics.
Gebe jedem «Ding» eine ID (=URI)
 Jede Ressource hat eine eindeutige URI
 https://www.googleapis.com/freebase/v1/search?query=sit
ecore&indent=true
 http://p.namics.com/dscherrer
 Usw.
30.04.2015 18 Denken. Präsentieren. Umsetzen.

19. Namics.
Benutze Hyperlinks als Verknüpfung der «Dinge»
30.04.2015 Denken. Präsentieren. Umsetzen.19
Wie geht das im Web? Hypermedia-Contxext schaffen
-> Benutze Link-Attribute! (rel, ref, self, type, allow, …)

20. Namics.
Benutze Standard-Methoden
 GET
 POST
 PUT
 DELETE
 HEAD
 OPTIONS
30.04.2015 Denken. Präsentieren. Umsetzen.20
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

21. Namics.
Benutze Standard-Methoden
 GET
 Ressource wird angefordert (URI) = read
 Accept-Header definiert Repräsentation
 Query-Parameter sind lediglich Filter/Selektoren
 HTTP Statuscodes berücksichten!
30.04.2015 Denken. Präsentieren. Umsetzen.21
...
Request URL:
http://api.interhome.com/accommodations/CZ3940.210.1/?language=de&country=CH&curre
ncy=CHF&salesOfficeCode=2020
Accept: Application/json
Accept-Language:en-US,en
Host: api.interhome.com
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/27.0.1453.116 Safari/537.36
...

22. Namics.
Benutze Standard-Methoden
 POST
 Erzeugt eine neue Ressource -> Server ist führend für die
URI-Generierung (im Gegensatz zu PUT)
 StatusCodes sind sehr wichtig! (Conflict, Created, No
Content, usw.)
 Content-Type-Header angeben!
 Wenn eine Ressource erzeugt wurde, wird im Response-
Header «Location» die ID (URI) der Ressource mitgeteilt
 POST’s werden nie gecached!
30.04.2015 Denken. Präsentieren. Umsetzen.22

23. Namics.
Benutze Standard-Methoden
 PUT
 Aktualisiert / erzeugt eine Ressource -> keine partiellen
Updates.
 URI wird von dem Client definiert (im Gegensatz zu POST)
 StatusCodes sind sehr wichtig! (Ok, No Content, Not
Implemented, Created)
 PUTs werden nie gecached!
30.04.2015 Denken. Präsentieren. Umsetzen.23

24. Namics.
Benutze Standard-Methoden
 DELETE
 Löscht eine Ressource
 StatusCodes sind sehr wichtig! (Ok, Accepted, No
Content)
 DELETE’s werden nie gecached
30.04.2015 Denken. Präsentieren. Umsetzen.24

25. Namics.
Benutze Standard-Methoden
 OPTIONS
 Gibt an, wie die Ressource verwendet werden darf
(Content-Type’s, Allows anderer Methoden, usw.)
 Ist die Dokumentation der Ressource
30.04.2015 Denken. Präsentieren. Umsetzen.25
...
Server: Apache/2.4.1 (Unix) OpenSSL/1.0.0g
Allow: GET,HEAD,POST,OPTIONS,TRACE
Content-Type: httpd/unix-directory
...
{ "POST": { "description": "Create an issue", "parameters": { "title": { "type": "string"
"description": "Issue title.", "required": true }, "body": { "type": "string", "description": "Issue
body.", }, "assignee": { "type": "string", "description" "Login for the user that this issue should
be assigned to." }, "milestone": { "type": "number", "description": "Milestone to associate this
issue with." }, "labels": { "type": "array/string" "description": "Labels to associate with this
issue." } }, "example": { "title": "Found a bug", "body": "I'm having a problem with this.",
"assignee": "octocat", "milestone": 1, "labels": [ "Label1", "Label2" ] } } }

26. Namics.
Benutze Standard-Methoden
 HEAD
 Wird genau gleich angewendet wie GET, jedoch ohne die
eigentliche Ressource zu erhalten
 Header Informationen / StatusCodes im Fokus:
30.04.2015 Denken. Präsentieren. Umsetzen.26
...
Cache-Control: public, max-age=60
Content-Type: application/json; charset=utf-8
Vary: Accept
X-RequestID: ebf0b09f-7a9b-407b-a09d-ea640b9b4d56
X-Response-Irent: 15.04
Content-Length: 6193
Accept-Ranges: bytes
Date: Tue, 09 Jul 2013 09:14:37 GMT
X-Varnish: 1496578512
Age: 0
Via: 1.1 varnish
Connection: keep-alive
...

27. Namics.
«Dinge» haben mehrere Repräsentationen
 Gleiche Ressource, verschiedene Repräsentationen
 HTML, Json, Protobuf, XML, CSV, BusinessObjects, usw.
 Accept Request-Header definiert Repräsentation
30.04.2015 Denken. Präsentieren. Umsetzen.27
GET
PUT
POST
DELETE
HEAD
OPTIONS
/conference/tracks/6

28. Namics.
«Dinge» haben mehrere Repräsentationen
 GET http://p.namics.com/dscherrer
 Accept: application/json
Oder application/vnd.namics.people+json
30.04.2015 Denken. Präsentieren. Umsetzen.28
{
"firstname": "Daniel",
"lastname" : "Scherrer",
"function" : "Senior Software Architect",
" picture" : "https://www.namics.com/uploads/tx_nezzonamicsemployee/daniel_scherrer.jpg",
"isActive": true,
"Address": {
"name" : "Namics AG",
"street" : "Teuefenerstrasse 19",
"zip" : 9001,
"place" : "St. Gallen"
},
"Contact": {
"phoneBusiness" : "+41 71 228 67 79",
"phoneMobile" : "+41 79 746 79 75",
"eMail" : "daniel.scherrer@namics.com",
"skype" : "daniiiol",
"google+" : "https://plus.google.com/110208095020222465456/"
}
}

29. Namics.
«Dinge» haben mehrere Repräsentationen
 GET http://p.namics.com/dscherrer
 Accept: text/html
Oder application/vnd.namics.people+html
30.04.2015 Denken. Präsentieren. Umsetzen.29
Interpretiert:
<div class="ct_nx_item">
<div class="nx_item merkur1">
<div class="front face">
<div class="turnpage"></div>
<h2>Daniel Scherrer.</h2>
<h3>Senior Software Architect</h3>
<h4>Direkt +41 71 228 67 49</h4>
<h5>
dipl. Wirtschaftsinformatiker HF<br />
&#x64;&#x61;&#x6e;&#x69;&#x65;&#x6c;&#x2e;&#x73;&#x63;&#x68;&#x65;&#x72;&#x72;&#x65;&#x72;&#x40;&#x6e;&#x61;&#x6d;&#x69;&#x63;&#x
73;&#x2e;&#x63;&#x6f;&#x6d;<br />
<br />
Skype: daniiiol<br /><br />
<strong>St. Gallen</strong>, Teufenerstrasse 19 , CH-9001 St. Gallen<br />
Telefon +41 [0] 71 228 67 77, Fax +41 [0] 71 228 67 88 <br />
info@namics.com, www.namics.com, dialog.namics.com
</h5>
</div><!--end front-->
<div class="back face">
<h1>Hilfsbereit. Ehrgeizig. Technologieverliebt. Programming. <span> Namics.</span></h1>
<div class="turnpage"></div>
</div><!--end back -->
</div><!--end nx_item-->
<br/>
<a href="dscherrer.vcf" target="_blank" title="Download VCard" ><img
src='/img/vcard-icon.jpg' width="30" height="30" alt="Download VCard" /></a>
&nbsp;<a
href="http://www.twitter.com/daniiiol" target="_blank" title="Twitter"><img src='/img/twitter-icon.jpg' width="30" height="30" alt="Twitter" /> </a>
&nbsp;<a
href="http://www.facebook.com/scherrer" target="_blank" title="Facebook"><img src='/img/facebook-icon.png' width="30" height="30" alt="Facebook" /> </a>
&nbsp;<a
href="https://plus.google.com/u/0/110208095020222465456" target="_blank" title="GPlus"><img src='/img/gplus-icon.jpg' width="30" height="30" alt="GPlus" /> </a>
&nbsp;<a
href="https://www.xing.com/profile/Daniel_Scherrer3" target="_blank" title="Xing"><img src='/img/xing-icon.jpg' width="30" height="30" alt="Xing" /> </a>
&nbsp;<a href="skype:daniiiol"
target="_blank" title="Skype"><img src='/img/skype-icon.jpg' width="30" height="30" alt="Skype" /> </a>
</div><!--ct_nx_item -->

30. Namics.
«Dinge» haben mehrere Repräsentationen
 GET http://p.namics.com/dscherrer
 Accept: image/jpeg
Oder application/vnd.namics.people+jpeg
30.04.2015 Denken. Präsentieren. Umsetzen.30

31. Namics.
Richardson’s Maturity Model
30.04.2015 Denken. Präsentieren. Umsetzen.31

32. Namics.
Warum REST und nicht WS* ?.

33. Namics.
Allgemein
 WS* Services
 Oft SOAP als Übermittelungsvariante & WSDL als
Interface-Beschreibung
 Unterstützt mehrere Protokolle (nicht nur HTTP!)
 Plattformunabhängig / Programmiersprachenunabhängig
 XML ist gesetzt und eher «schwergewichtig» aber
strukturiert
 Die eigentliche Nachricht (Body) ist nur ein kleiner Teil der
ganzen Informationsübermittelung
 Nicht zustandslos
 Fehler-Container ist standardisiert
30.04.2015 33 Denken. Präsentieren. Umsetzen.

34. Namics.
Allgemein
 Rest Services
 Ist kein Standard
 Plattform-/Programmiersprachenunabhängig
 ROA
 Auf HTTP beschränkt
 Zustandslos
30.04.2015 34 Denken. Präsentieren. Umsetzen.

35. Namics.
Implementierung
30.04.2015 35 Denken. Präsentieren. Umsetzen.
Die Verwendung einer Web-Service-Schnittstelle dagegen
erfordert Spezialkenntnisse bzw. ein genau dafür kodiertes
Programm: an solchen Stellen ist das Web „zu Ende“.
Der SOAP- und WSDL- Begriff „Endpoint“ passt hier sehr gut.
Stefan Tilkov

36. Namics.
Interface
 WS* Services
 Designed für Leute, welche den Schlüssel zum System
haben und genau wissen wie es zum implementieren ist
 Bspw. Über eine WSDL/SOAP wird das Interface
beschrieben, welches anschliessend implementiert
werden muss
 Rest Services
 Designed für Leute, welche verstehen wie HTTP-
Interaktionen funktionieren
 Generische Clients wie curl, wget, proxies, caches, http
servers, gateways, browsers & Google ;-)
30.04.2015 36 Denken. Präsentieren. Umsetzen.

37. Namics.
Sicherheit
 WS* Services
 WS-Security ist sehr mächtig und bietet alle
Sicherheitsstufen (Vetraulichkeit & Integrität) von der
Kreierung der Nachricht bis und mit Konsum dar
 Rest Services
 HTTPS stellt die Sicherheit der Nachrichtenübermittelung
dar
30.04.2015 37 Denken. Präsentieren. Umsetzen.

38. Namics.
Wie haben wir mit WS* Service designt?
 Die Tätigkeit/Prozessschritt war im Fokus
30.04.2015 38 Denken. Präsentieren. Umsetzen.
Service 1
Service 2

39. Namics.
Wie designen wir mit REST?
 Die Ressource & die Standard-Methoden
30.04.2015 39 Denken. Präsentieren. Umsetzen.

40. Namics.
Wie war die Kommunikation?
 Klassische Service-Interfaces
30.04.2015 Denken. Präsentieren. Umsetzen.40
Client 1
Client 2
Client n
…
Server

41. Namics.
Wie ist die Kommunikation mit REST-Service?
 Hypermedia verändert das klassische Denken
30.04.2015 Denken. Präsentieren. Umsetzen.41
Client 1
Client 2
Client n
…
Server 1
Server 2
Server n
…
Format

42. Namics.
Gegenüberstellung
 SOAP fordert eine grössere Bindung an die Clients ->
bei einer Veränderung des Servers muss der Client
angepasst werden
 REST ist freundlicher für Netzwerkkomponenten und
Administratoren (Firewall-Rules auf URI oder HTTP-
Methoden)
 SOAP kann nicht gecached werden, da POST’s gemacht
werden
 SOAP hat einen grossen Overhead
 REST lässt sich durch seine Statuslosigkeit sehr einfach
skalieren
 SOAP ist ein Standard, REST nicht
30.04.2015 42 Denken. Präsentieren. Umsetzen.

43. Namics.
Trend?
 WWW (REST) gabs schon lange vor SOAP (1999)
 Roy Fielding: „SOAP was known to be a bad idea in 1999,
but in spite of our comments to this effect, the industry
insisted on proving that for themselves”.
30.04.2015 Denken. Präsentieren. Umsetzen.43

44. Namics.
Good-Practices / Fallstricke.

45. Namics.
Grundregel: Postel’s Law
“TCP implementations should follow a general principle of
robustness: Be conservative in what you do, be liberal in
what you accept from others.”
http://tools.ietf.org/html/rfc761
30.04.2015 Denken. Präsentieren. Umsetzen.45

46. Namics.
Grundregel : Postel’s Law
30.04.2015 Denken. Präsentieren. Umsetzen.46

47. Namics.
HATEOAS
“The next control state of an application resides in the
representation of the first requested resource, … The
application state is controlled and stored by the user agent …
anticipate changes to that state (e.g., link maps and prefetching
of representations) … The model application is therefore an
engine that moves from one state to the next by examining and
choosing from among the alternative state transitions in the
current set of representations.”
Roy T. Fielding
30.04.2015 Denken. Präsentieren. Umsetzen.47

48. Namics.
HATEOAS
30.04.2015 Denken. Präsentieren. Umsetzen.48

49. Namics.
HATEOAS
 Hypermedia As The Engine Of Application State
 Prozessgedanke in der Ressource
 Media-Typen beschreiben die Ressource
 Aktionen werden ausgeführt beim folgen von Links
 Jede Antwort beinhaltet den «Application State»
 Es ist gut, eigene Media-Typen zu erstellen
(domänenspezifisches Applikations-Protokoll)
 Selbstbeschreibende API’s erzeugen Flexibilität
 Clients können die API «erforschen» ohne Dokumentation
und Anleitung
30.04.2015 Denken. Präsentieren. Umsetzen.49

50. Namics.
HATEOAS
30.04.2015 Denken. Präsentieren. Umsetzen.50

51. Namics.
Prozessabbildung: State ist stets beim Client
30.04.2015 Denken. Präsentieren. Umsetzen.51

52. Namics.
Benutze Hyperlinks als Verknüpfung der «Dinge»
 Twitter Example
30.04.2015 Denken. Präsentieren. Umsetzen.52

53. Namics.
Benutze Hyperlinks als Verknüpfung der «Dinge»
 eBay Example
30.04.2015 Denken. Präsentieren. Umsetzen.53

54. Namics.
Benutze Hyperlinks als Verknüpfung der «Dinge»
 Links können zielgerichteter sein
 Vereinfacht die Maintenance u.U.
30.04.2015 Denken. Präsentieren. Umsetzen.54
«link» : {
«type» : «application/vnd.namics.conference.track+json;v=2»,
«rel» : «Show Detail»,
«href» : «http://conf.namics.com/api/conference/tracks/5»
}
«link» : {
«type» : «application/vnd.namics.conference.track+json;v=2»,
«rel» : «Show Detail»,
«href» : «http://conf_1.namics.com/api/conference/tracks/5»
}
! Die ganze conf-Zone geht down für Wartung – Umleitung muss geschehen…

55. Namics.
HATEOAS
 Vorteile von Hateoas
 Caches können feingranularer gesetzt werden
 Der langsamste Aufruf innerhalb der API beeinflusst nicht
die Gesamtdauer der Response-Zeit
 Der RESTful Weg mit Application State’s umzugehen
 Die API ist selbsbeschreibend und somit crawlbar
 Nachteile von Hateoas
 Ein Seitenrequest erzeugt n Requests auf die API
 Hateoas verknüpft Ressourcen konzeptionell führt aber
keine Relationen aktiv aus
 Viel mehr Cache-Entries in der Anzahl
30.04.2015 Denken. Präsentieren. Umsetzen.55

56. Namics.
Nicht puristisch denken. Yoga-Pause machen
 Yoga fügt Relation-Selektoren zu REST hinzu
 Public
 GET /user/1.json?selector=$friendsFavoriteMusic
 Internal
 GET /user/1.json?selector=friends(favoriteArtists(albums(songs)))
 HATEOAS als Minimum-Prinzip anschauen
 HATEOAS = GET /user/1.json?view=small
 Zu den Links auch die Objekte inkludieren = GET /user/1.json?view=full
 Und alles dazwischen natürlich…
 Yoga-Frameworks für Spring, Jersey ohne Spring, RESTeasy
 http://yoga.skyscreamer.org/
30.04.2015 Denken. Präsentieren. Umsetzen.56

57. Namics.
Richtige Abstraktionsstufen wählen
 Bausteingedanke hilft einem im Aufbau stark
 Definition der Ressourcen-Hierarchie
 Nicht alles von der DB muss auch in die API rein
 Schnittstellen = Referenzen / inkludierte Objekte
 Nicht alles muss eine Ressource sein (1:1 Beziehungen
erkennen)
 Beispiel HATEOAS
 Erzeugt sehr viele Requests, dafür nur Daten, die
gebraucht werden – Caching besser möglich
30.04.2015 57 Denken. Präsentieren. Umsetzen.

58. Namics.
Richtige Abstraktionsstufen wählen
 Caches können feingranularer gesetzt werden
30.04.2015 Denken. Präsentieren. Umsetzen.58
GET ../products/1234/ - RESPONSE
Produkt Metadaten
Preisinformationen
Verfügbarkeiten
Header-Informationen
Cache-Control: public;max-age=60
GET ../products/1234/ - RESPONSE
Header-Informationen
Cache-Control: public;max-age=3600
Produkt Metadaten
Header-Informationen
Cache-Control: public;max-age=3600
Preisinformationen
Header-Informationen
Cache-Control: public;max-age=60
Verfügbarkeiten
Header-Informationen
Cache-Control: public;max-age=300

59. Namics.
Richtige Abstraktionsstufen wählen
 Ganzes Paket in Bytes
30.04.2015 Denken. Präsentieren. Umsetzen.59
GET ../products/1234/ - RESPONSE
Produkt Metadaten
Preisinformationen
Verfügbarkeiten
Header-Informationen
Cache-Control: public;max-age=60
1000 bytes / 5ms
500 bytes / 100ms
2000 bytes / 50ms
400 bytes
3900 bytes

60. Namics.
Richtige Abstraktionsstufen wählen
 Alle Pakete und ihre Byte-Grössen
30.04.2015 Denken. Präsentieren. Umsetzen.60
1000 bytes / 10ms
500 bytes / 105ms
2000 bytes / 55ms
400 bytes
5500 bytes
GET ../products/1234/ - RESPONSE
Header-Informationen
Cache-Control: public;max-age=3600
Produkt Metadaten
Header-Informationen
Cache-Control: public;max-age=3600
Preisinformationen
Header-Informationen
Cache-Control: public;max-age=60
Verfügbarkeiten
Header-Informationen
Cache-Control: public;max-age=300
400 bytes
400 bytes
400 bytes
400 bytes / 5ms

61. Namics.
Richtige Abstraktionsstufen wählen
 Annahme
 Requests in 2 Stunden (linear)
 7200x Produktmetadaten (jede Sek)
 5400x Preisinformationen (jede 1.5 Sek)
 900x Verfügbarkeiten (jede 8. Sek)
 Ohne Hateoas
 7200 / 60 * 3900 = 468kb (120 API Calls)
 Mit Hateoas
 2x 800kb & 2x 1400kb & 120x 900kb & 24 x 2400kb
= 170kb (148 API Calls)
30.04.2015 Denken. Präsentieren. Umsetzen.61

62. Namics.
Richtige Abstraktionsstufen wählen
 Annahme
 Requests in 2 Stunden (linear)
 7200x Produktmetadaten (jede Sek)
 5400x Preisinformationen (jede 1.5 Sek)
 900x Verfügbarkeiten (jede 8. Sek)
 Ohne Hateoas
 7200 / 60 * 155ms = 18,6s (120 API Calls)
 Mit Hateoas
 2x 5ms & 2x 10ms & 120x 105ms & 24x 55ms
= 13,95s (148 API Calls)
30.04.2015 Denken. Präsentieren. Umsetzen.62

63. Namics.
Richtige Abstraktionsstufen wählen
 Fazit
 Ob sich HATEOAS lohnt ist von vielen Faktoren abhängig
und kann nicht pauschal «be’ja’t» werden:
 Wenige Konsumenten vs. Public API
 Komplexität der Objekte – Anzahl Referenzen und Tiefe
 Architektur der Webseite – sehr dynamisch oder statisch
 Grösse der Infrastruktur – low aber viele Server vs.
wenige aber powerfull
 Gültigkeitsunterschied der Objekte – viele & grosse
Deltas
30.04.2015 Denken. Präsentieren. Umsetzen.63

64. Namics.
Versionierung
 Variante 1
 Media-Type = Versionsnummer
 Accept: application/vnd.namics.conference.track-v2+json
 Variante 2
 Media-Type verändern sich nicht, ein Qualifier wird
hinzugefügt
 Accept: application/vnd.namics.conference.track+json;v=2
 Version 3
 Version wird in der URI gesetzt
 GET /api/v2/conference/tracks/6
30.04.2015 64 Denken. Präsentieren. Umsetzen.

65. Namics.
Versionierung
 Welche ist die Beste?
 Zwischen 1 und 2 liegen feine Unterschiede
(MediaType/Format), meist eine Konzept-, Implementierungs-
und Wartungsfrage.
 3. Ist die verbreiteste Variante – verletzt aber das Prinzip das
eine Ressource genau eine URI besitzt – Version hat mit der
Repräsentation zu tun und nicht mit dem «Ding» als solches
 3. Ist für die Versionierung der API bzw. der Ressource für sich
verantwortlich. Im Normalfall möchte man die MediaTypen und
dessen Formate und nicht die API versionieren
 Das Beste? Keine Versionierung! 
30.04.2015 65 Denken. Präsentieren. Umsetzen.

66. Namics.
Sicherheit
“REST means working with the standards of the web, and the
standard for "secure" transfer on the web is SSL. Anything else
is going to be kind of funky and require extra deployment effort
for clients, which will have to have encryption libraries
available.”
Highest rated answer on stackoverflow regarding REST
authentication schemes
30.04.2015 66 Denken. Präsentieren. Umsetzen.

67. Namics.
Sicherheit
 SSL! Aber genügt uns das?
 HTTPS löst nicht das man-in-the-middle Problem
 Nur Transport-Sicherheit
 REST hat keine Nachrichtenintegrität oder Authentisierung
 OAuth ist super (und komplex) für Authentifizierung – hat
aber keine Nachrichtensicherheit
 REST hat keinen WS-Security-Standard
30.04.2015 67 Denken. Präsentieren. Umsetzen.

68. Namics.
Sicherheit
 Was könnte gehen?
 HTTP basic auth über HTTPS
 Cookies und Session Management
 Query Auth. mit zusätzlichen Signatur-Parametern
30.04.2015 68 Denken. Präsentieren. Umsetzen.

69. Namics.
Sicherheit
 HTTP basic auth über HTTPS
 Basiert auf den Standards von HTTPS
 Benutzt von den meisten Web-Services
 Einfach zu implementieren
 Verfügbar bei nahezu allen Browsern
 Es gibt kein Log-Out-Feature
 Hohe CPU-Werte auf Serverseite
 Username & Password wird übermittelt
30.04.2015 69 Denken. Präsentieren. Umsetzen.

70. Namics.
Sicherheit
 Cookies und Session Management
 Sessions sind nicht Stateless (!)
 By design wird das Cookie auf Server-Seite verarbeitet,
aber Client-Seitig gespeichert – Application State ist Sache
des Clients!
30.04.2015 70 Denken. Präsentieren. Umsetzen.

71. Namics.
Sicherheit
 Query Auth. mit zusätzlichen Signatur-Parametern
 Eigener Mechanismus – kein Standard
 Client muss Implementierung kennen
 Chance REST und seine Prinzipien zu unterstützen… ;-)
30.04.2015 71 Denken. Präsentieren. Umsetzen.

72. Namics.
Sicherheit
 HMAC basierende Authentifizierung als Lösung
 Wird von grossen Unternehmen verwendet (Google,
Amazon AWS, Yahoo, usw.)
 Erstellt eine eindeutige Signatur des kompletten Requests
mit einem sicheren Schlüssel
 Fügt einen Custom-Header hinzu mit Signatur und
Benutzerinformation
 Shared Secret
 URI, Verb, MD5-Header, Content-Type, Date-Header
30.04.2015 72 Denken. Präsentieren. Umsetzen.

73. Namics.
Sicherheit
 Nochmals ganz kurz erklärt (AWS): Der Request
 Der Canonical String auf Basis des Requests:
30.04.2015 Denken. Präsentieren. Umsetzen.73
PUT /quotes/nelson HTTP/1.0
Content-Md5: c8fdb181845a4ca6b8fec737b3581d76
Content-Type: text/html
Date: Thu, 17 Nov 2005 18:49:58
GMT X-Amz-Meta-Author: foo@bar.com
X-Amz-Magic: abracadabra
Var str =
„PUTnc8fdb181845a4ca6b8fec737b3581d76ntext/htmln
Thu, 17 Nov 2005 18:49:58 GMTn
x-amz-magic:abracadabran
x-amz-meta-author:foo@bar.comn/quotes/nelson“

74. Namics.
Sicherheit
 Die HMAC-Generierung
 Secret Key ist der Private-Schlüssel
30.04.2015 Denken. Präsentieren. Umsetzen.74
import base64
import hmac
import sha
h =
hmac.new("OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV",
"PUTnc8fdb181845a4ca6b8fec737b3581d76ntext/htmlnThu,
17 Nov 2005 18:49:58 GMTnx-amz-magic:abracadabran
x-amz-meta-author:foo@bar.comn/quotes/nelson",
sha)
base64.encodestring(h.digest()).strip()

75. Namics.
Sicherheit
 Request an den Server
 AWS Access Key ID = 44CF9590006BF252F707
 Public Key
 Unser HMAC = jZNOcbfWmD/A/f3hSvVzXZjM2HU=
 Sicherheitstoken
30.04.2015 Denken. Präsentieren. Umsetzen.75
PUT /quotes/nelson HTTP/1.0
Authorization: AWS 44CF9590006BF252F707:jZNOcbfWmD/A/f3hSvVzXZjM2HU=
Content-Md5: c8fdb181845a4ca6b8fec737b3581d76
Content-Type: text/html
Date: Thu, 17 Nov 2005 18:49:58 GMT
X-Amz-Meta-Author: foo@bar.com
X-Amz-Magic: abracadabra

76. Namics.
Sicherheit
 Sicherheit ?
 HTTPS stellt die Transportsicherheit her
 Nachrichtenintegrität wird durch MD5-Hash hergestellt
 Timestamp hilft gegen Replay-Attacks
 Authentifizierung mittels Private- & Public-Key ist
sichergestellt
 Es wird nie ein Passwort übermittelt
30.04.2015 Denken. Präsentieren. Umsetzen.76
PUT /quotes/nelson HTTP/1.0
Authorization: AWS 44CF9590006BF252F707:jZNOcbfWmD/A/f3hSvVzXZjM2HU=
Content-Md5: c8fdb181845a4ca6b8fec737b3581d76
Content-Type: text/html
Date: Thu, 17 Nov 2005 18:49:58 GMT
X-Amz-Meta-Author: foo@bar.com
X-Amz-Magic: abracadabra

77. Namics.
Spezifikation eines Services
 Generierte Spezifikation
 WSDL von Rest = WADL (Web Application Description
Language)
 http://www.w3.org/Submission/wadl/#x3-330005
 Spezifikation im Service
 HTTP Methode OPTIONS verwenden
 Wiki
 Komplett losgelöst von der Technik
 Beispiel:
https://wiki.namics.com/display/interhomebl/Home
30.04.2015 77 Denken. Präsentieren. Umsetzen.

78. Namics.
Spezifikation eines Services
 Wiki
 Spezifiziert den Service konzeptionell
 Diskussionsgrundlage für Konzept/Implementierung
 Kümmert sich auch um architektonische Themen
 Beschreibt die Schnittstelle grafisch & textuell
 Ist ein Abnahmeprotokoll für die definierten Stakeholder
30.04.2015 78 Denken. Präsentieren. Umsetzen.

79. Namics.
Spezifikation eines Services
 Generierte Spezifikation – WADL
 Diskussion über WADL ist gross
30.04.2015 79 Denken. Präsentieren. Umsetzen.

80. Namics.
Spezifikation eines Services
 HTTP OPTIONS
 Funktionalitäten von HTTP werden verwendet – keine
zusätzlichen XSD’s
 Header-Infos sind standardisiert (Body nicht).
 OPTIONS hat den Fokus die Ressource für sich zu
spezifizieren – nicht den ganzen Service
 Schnittstelle über Options zu spezifizieren löst die Starrheit
von WADL
30.04.2015 80 Denken. Präsentieren. Umsetzen.

81. Namics.
Spezifikation eines Services
 To WADL or not to WADL?
 Umso mehr Konsumenten einer dynamischen API, umso
weniger WADL
 Umso statischer der API Ausbau, umso eher WADL
 Kurzfristig gesehen (Projektsicht) ist WADL sehr effizient
 … es gibt aber kein einheitliches Rezept!
 WADL ersetzt aber kein Wiki-Dokument für die
Konzipierung eines Services!
30.04.2015 Denken. Präsentieren. Umsetzen.81

82. Namics.
Entwicklungsvorgehen
 Die Use Cases definiert die Funktionalität
 Rahmenbedingungen & Qualitätsanforderungen des
Projektes betreffen tiefere Schichten nahezu immer mit
 Ohne Architekturkonzept keine Implementierung
 Vorgehen ist iterativ – alles andere wäre Utopie
 Kommunikation ist der Masterkey zum Erfolg!
 Bei paralleler Entwicklung mit Stubs gemäss Konzept
arbeiten
30.04.2015 82 Denken. Präsentieren. Umsetzen.

83. Namics.
Funktionale Anforderungen & REST
 Beachte: Beim Bau eines Rest-Services ist man oft
Anbieter und Konsument gleichzeitig
30.04.2015 83 Denken. Präsentieren. Umsetzen.
Webseite
REST-Service
Daten
Spezifikation

84. Namics.
Nicht funktionale Anforderungen & REST
 Nicht funktionale Anforderungen sind meist
projektkritischer als funktionale Anforderungen
(Aber es wird selten darüber geredet…)
30.04.2015 Denken. Präsentieren. Umsetzen.84
REST-Service
Daten
Performance
40ms
90ms
40+90+x=300ms
Seite muss
in 300ms
geladen
werden
Webseite

85. Namics.
Entwicklungsvorgehen : Ablauf
30.04.2015 85 Denken. Präsentieren. Umsetzen.
Kunde &
Requirements Engineer
Architekt Software Engineers
BL
Tester / QSSoftware Engineers
Frontend
Stubs erstellen
Testing
Anforderungen Konzept Test-Konzept
Implementieren Gemäss Stubs impl.
Testing impl.

86. Namics.
Tools.
30.04.2015 86 Denken. Präsentieren. Umsetzen.

87. Namics.
Rest-Services benutzen
30.04.2015 87 Denken. Präsentieren. Umsetzen.
Dev HTTP Client
Chrome Extension
HTTP Requests ausführen
und analysieren

88. Namics.
Rest-Services benutzen
30.04.2015 88 Denken. Präsentieren. Umsetzen.
Advanced REST Client
Chrome Extension
HTTP Requests ausführen
und analysieren

89. Namics.
Rest-Services benutzen
30.04.2015 89 Denken. Präsentieren. Umsetzen.
Fiddler 2
Windows Application
HTTP Requests ausführen
und analysieren

90. Namics.
Rest-Services benutzen
30.04.2015 90
SoapUI
WebService Swiss-Army-Knife
WADL-Service-Analysieren, Testing,
konzipieren, Java Code-Generierung
(Jersey 1.x, JAX-RS 2.x proxy based client

91. Namics.
Rest-Services benutzen
30.04.2015 91
Apache JMeter
Load Testing
Stress-, Load-Tests für REST-Service

92. Namics.
Abschluss
30.04.2015 92 Denken. Präsentieren. Umsetzen.

93. Namics.
Rest-Services benutzen
30.04.2015 93
Weg mit dem Rest
Behalte Übersicht.
Sich nicht verschliessen.
Verständnis und Einfachheit schaffen.

94. Namics.
Bist Du auch ein RESTafarian?
daniel.scherrer@namics.com
© Namics
94

95. 30.04.2015 95 Denken. Präsentieren. Umsetzen.