Web-APIs sind das aktuelle Trendthema in den IT-Abteilungen. Als primärer Kommunikationspartner für Fat-, Mobil- und Web-Clients sind Web-APIs das Rückgrat moderner verteilter Anwendungen. Sind synchrone Requests via REST und GraphQL oder Push-Notifications via Server-Sent Events und WebSocket die bessere Wahl? Welches Austauschformat sollte man wählen? Wie sieht gutes "Error Handling" aus? Und was ist mit Themen wie Security und Versionierung? Lebensnahe Beispiele, jede Menge Best-Practices und viel Code, der nahtlos in eigene Projekte übernommen werden kann, bilden die Grundlage für die Session.

1. #WISSENTEILEN
@_openKnowledge
API-First
Design mit
Web-API Design
mit Java

2. BRANCHENNEUTRALE SOFTWAREENTWICKLUNG UND IT-BERATUNG
ÜBER OPEN KNOWLEDGE

3. ÜBER UNS
Wer bin ich - und wenn ja, wie viele?
• Enterprise Architect
• Enterprise & mehr
• Autor, Speaker, Berater, Coach
• Tauch & Ski Enthusiast
• Grillmeister & Hobbygärtner ;)
STEPHAN MÜLLER
SM

4. #WISSENTEILEN
“API design should not be constrained by
what can be done giving existing limitations,
but rather by what should be done.”
Jennifer Riggins, ProgrammableWeb

5. #WISSENTEILEN
„Das* API ist das
UI des Entwicklers.“
(*wer möchte, darf auch “die API“ sagen)

6. #WISSENTEILEN
„Entscheidend ist, dass das API aus
Sicht des Entwicklers konsistent und
leicht anwendbar ist.

7. #WISSENTEILEN
Event-Feed
WebSocket
Server-SentEvents
GraphQL
REST
Web-APIs

8. #WISSENTEILEN
Beispielanwendung: Todo-Liste

9. #WISSENTEILEN
Todo App
SPA
Todo Service
JEE
REST
GraphQL
Event-Feed
WebSocket
Server-Sent Events
Web-APIs

10. #WISSENTEILEN
REST
Web-APIs
- REpresentational State Transfer
- Architekturstil definiert von Roy Fielding
- Ausnutzung „aller“ HTTP Methoden & Hypermedia
- „beliebige“ Mediatypes / Datenformate
Hypermedia
URI
HTTP

11. #WISSENTEILEN
GraphQL
Web-APIs
- SQL-Like Query Language
- von Facebook als Alternative zu REST entwickelt
- komplexe Abfragen via Objekt-Graph möglich
- liefert Abfrageergebnis in einem einzigen Round-Trip
- mehr Flexibilität für Clients

12. #WISSENTEILEN
Server-SentEvents
Web-APIs
- W3C Standard für Server-Push
- Sendet UTF-8 Daten vom Server zum Client
- definierte Datenstruktur & Media-Type für Event
- initialer Verbindungsaufbau durch Client
- built-in Support für reconnect (Timeout)
- aber Anzahl paralleler Verbindungen begrenzt

13. #WISSENTEILEN
WebSocket
Web-APIs
- W3C Standard für Full-Duplex Kommunikation
- Socket-Verbindung über TCP
- lediglich EINE Connection (up/down)
- extrem leichtgewichtig dank HTTP Upgrade
- Low-Level Protokoll ohne Header, Statuscodes, etc.

14. #WISSENTEILEN
Event-Feed
Web-APIs
- API zur Bereitstellung von Events
- ermöglicht Clients Ereignisse zu verarbeiten
- Anwendung u.a. beim Event-Sourcing
- Atom, Kafka Streams (nur mit Apache Kafka)

15. #WISSENTEILEN
Web-APIs
NewTodo
- title: string
- description: string
- dueDate: date-time
- done: boolean
ModifiedTodo
- title: string
- description: string
- dueDate: date-time
- done: boolean
TodoList
- id: int64
- title: string
- dueDate: date-time
- done: boolean
TodoFull
- id: int64
- title: string
- description: string
- dueDate: date-time
- done: boolean
TodoEvent
- changeType: enum
- changeDate: date-time
- todo: TodoFull
Write-Modell Read-Modell Event-Modell Feed-Modell
Feed (ASF)
- id: URI
- title: string
- subtitle: string
- …

16. #WISSENTEILEN
Web-APIs - Dokumentation
ü Aufrufe und Abfragen sind dokumentiert
ü Beispiele für die erwartete und zu erwartende Payload
→ OpenAPI Specification (fka Swagger)
→ GraphQL Schema

17. #WISSENTEILEN
Web-APIs - Dokumentation

18. #WISSENTEILEN
Web-APIs - Payload
ü effizient, kompakt & schnell
ü breiter Language/Framework Support
ü Developer/IDE friendly
→ JSON == Native Web Format
→ binäres Format (Protocol Buffers, Apache Avro) wenn notwendig

19. #WISSENTEILEN
Web-APIs - Payload
REST GraphQL

20. #WISSENTEILEN
Web-APIs - Fehlerhandling
☹ Stacktraces
☹ falsche Statuscodes
☹ unerwartete Content-Types
☹ komplexe Datenstrukturen
☹ Textanalyse

21. #WISSENTEILEN
Web-APIs - Fehlerhandling
ü Fehler als alternative Antwort berücksichtigen
ü Fehlercode für client-spezifische Fehlermeldungen
ü Fehlernachricht für Entwickler & Operator
ü Fehlerart kenntlich machen (Statuscode, Fehlertyp)
→ einfache Fehlerdatenstruktur
→ in GraphQL über Extensions

22. #WISSENTEILEN
Web-APIs - Fehlerhandling
REST GraphQL

23. #WISSENTEILEN
Web-APIs - Validierung
ü transparente Prüfung der Anfragedaten
ü syntaktische Validierung (Pflichtfeld, Eingabelänge & -format)
ü semantische Validierung (mit Einschränkung)
ü individuelle Fehlercodes & verständliche Fehlermeldungen
→ Bean Validation
→ Custom Constraints für Crossfield & semantische Validierung
→ Payload für individuelle Fehlercodes

24. #WISSENTEILEN
Web-APIs - Validierung

25. #WISSENTEILEN
Web-APIs - Validierung
REST
GraphQL

26. #WISSENTEILEN
Web-APIs - Security
☹ Password wird bei jeder Anfrage übertragen (Basic Auth)
☹ Jeder Service muss Benutzer & Credentials kennen
☹ Benutzersession als State auf dem Server (Skalierbarkeit ⚡)
→ SSO Server als Identity Provider nutzen
→ Token based Security (OAuth2, OpenID_Connect)

27. #WISSENTEILEN
Web-APIs - Security
ü jeder Request wird einzeln autorisiert
ü rollen-basierte Zugriffskontrolle je Anfrage
ü Token liefert zusätzliche Informationen über Nutzer
→ JSON Web Token nutzen

28. #WISSENTEILEN
Web-APIs - Security

29. #WISSENTEILEN
Web-APIs - Versionierung
- Versionierung über URI
Variante 1: http://host/todo-service/api/todos-v2
Variante 2: http://host/todo-service/api/v2/todos
Variante 3: http://host-v2/todo-service/api/todos
- Versionierung über Accept-Header / custom Media-Type
z.B. application/vnd.ok.todo.v1+json

30. #WISSENTEILEN
http://apistylebook.com/design/guidelines/

31. #WISSENTEILEN
http://zalando.github.io/restful-api-guidelines/

32. #WISSENTEILEN
FRAGEN
? ? ?

33. Kontakt
STEPHAN MÜLLER
ENTERPRISE ARCHITECT
stephan.mueller@openknowledge.de
+49 (0)441 4082 – 0
@_openknowledge
OFFENKUNDIGGUT
#WISSENTEILEN

34. Bildnachweise
#01: © dzone.com
All other pictures inside this presentation orginate
from pixabay.com or were created by my own.
#WISSENTEILEN