Оглавление
Kai Spichale. API-Design
API-Design
Vorwort
Warum ist API-Design wichtig?
Eine Frage der Perspektive
Zielgruppe und Voraussetzungen
Struktur des Buches
Pfade durch das Buch
Danksagung
Inhaltsübersicht
Inhaltsverzeichnis
1Application Programming Interfaces – eine Einführung
1.1Eine kurze Geschichte der APIs
1.2Web-APIs ab dem Jahr 2000
1.3API-Definition
1.4Vorteile einer API
1.5Nachteile einer API
1.6API als Produkt
1.7Welche Strategien verfolgen Unternehmen mit APIs?
1.8Zusammenfassung
2Qualitätsmerkmale
2.1Allgemeine Qualitätsmerkmale
2.2Benutzbarkeit
2.2.1Konsistent
2.2.2Intuitiv verständlich
2.2.3Dokumentiert
2.2.4Einprägsam und leicht zu lernen
2.2.5Lesbaren Code fördernd
2.2.6Schwer falsch zu benutzen
2.2.7Minimal
2.2.8Stabil
2.2.9Einfach erweiterbar
2.3Konnaszenz
Was ist Konnaszenz?
Statische Konnaszenz
Dynamische Konnaszenz
2.4Zusammenfassung
3Allgemeines Vorgehen beim API-Design
3.1Überblick
3.2Heuristiken und Trade-offs
3.3Anforderungen herausarbeiten
3.4Wenn Use Cases nicht ausreichen
3.5Entwurf mit Szenarien und Codebeispielen
3.6Spezifikation erstellen
3.7Reviews und Feedback
3.8Wiederverwendung
3.9Zusammenfassung
4Ausprägungen
4.1Implizite Objekt-API
APIs nicht nur für Komponenten- und Teamgrenzen
API-Design fördert Clean Code
4.2Utility-Bibliothek
4.3Service
4.4Framework
4.5Eine Frage der Priorität
4.6Zusammenfassung
5Grundlagen für Java-APIs
5.1Auswahl passender Namen
5.1.1Klassennamen
5.1.2Methodennamen
Beschreibe alles, was die Methode macht!
Vermeide bedeutungslose Verben!
Ein Name ist so lang wie notwendig, aber nicht länger
Benenne Query-Methoden nach ihren Rückgabewerten!
Benenne Command-Methoden mit aussagekräftigen Verben!
Nutze etablierte Begriffe!
Nutze passende Antonyme!
5.1.3Parameternamen
5.1.4Ubiquitäre Sprache
5.1.5Fazit
5.2Effektiver Einsatz von Typen
5.2.1Semantischen Vertrag minimieren
5.2.2Semantische Verletzung der Datenkapselung vermeiden
5.2.3Werden Namen überschätzt?
5.2.4Fazit
5.3Techniken für Objektkollaboration
5.3.1Tell, Don’t Ask
5.3.2Command/Query Separation
5.3.3Law of Demeter
5.3.4Platzierung von Methoden
5.3.5Fazit
5.4Jigsaw-Module
Softwareerosion
5.5Minimale Sichtbarkeit
5.5.1Jigsaw-Module
5.5.2Packages
5.5.3Klassen
5.5.4Methoden
5.5.5Felder
5.5.6Fazit
5.6Optionale Hilfsmethoden
5.6.1Komfort
5.6.2Utility-Klassen
5.6.3Fazit
5.7Optionale Rückgabewerte
5.7.1Ad-hoc-Fehlerbehandlung
5.7.2Null-Objekte
5.7.3Verwendung der Klasse java.util.Optional
5.7.4Fazit
5.8Exceptions
5.8.1Ausnahmesituationen
5.8.2Checked Exception versus Unchecked Exception
5.8.3Passende Abstraktionen
5.8.4Dokumentation von Exceptions
5.8.5Vermeidung von Exceptions
5.8.6Fazit
5.9Objekterzeugung
5.9.1Erzeugungsmuster der GoF
5.9.2Statische Factory-Methode
Konkrete Namen
Wiederverwendung von Objekten
Flexible Erzeugung von Subtypen
5.9.3Builder mit Fluent Interface
5.9.4Praktische Anwendung der Erzeugungsmuster
Joda-Time Framework
MongoDB Java Client
5.9.5Fazit
5.10Vererbung
5.10.1Ansätze zum Einsatz von Vererbung
Open Inheritance
Designed Inheritance
5.10.2Stolperfallen bei Vererbung
5.10.3Bedeutung für API-Design
5.10.4Fazit
5.11Interfaces
5.11.1Typen nachrüsten
5.11.2Unterstützung für nicht triviale Interfaces
5.11.3Markierungsschnittstellen
5.11.4Funktionale Interfaces
5.11.5Fazit
5.12Zusammenfassung
6Fortgeschrittene Techniken für Java-APIs
6.1Fluent Interface
6.1.1DSL-Grammatik
6.1.2Schachteln versus Verketten
6.1.3Fluent Interface von jOOQ
6.1.4Ist der Aufwand gerechtfertigt?
6.1.5Fazit
6.2Template-Methoden
6.2.1API versus SPI
6.2.2Erweiterbare Parameter
6.2.3Fazit
6.3Callbacks
6.3.1Synchrone Callbacks
6.3.2Asynchrone Callbacks
6.3.3Fazit
6.4Annotationen
6.4.1Auswertung zum Kompilierzeitpunkt
6.4.2Auswertung zur Laufzeit
6.4.3Fazit
6.5Wrapper-Interfaces
6.5.1Proxy
6.5.2Adapter
6.5.3Fassade
Geschäftslogik zu Services orchestrieren
Abhängigkeiten kapseln
6.5.4Fazit
6.6Immutability
6.6.1Wiederverwendung
6.6.2Thread-Sicherheit
6.6.3Einfachheit
6.6.4Umsetzung
6.6.5Automatische Überprüfung mit dem Mutability Detector
6.6.6Codegenerierung mit Immutables
6.6.7Fazit
6.7Thread-sichere APIs
6.7.1Vorteile
6.7.2Nachteile
6.7.3Was bedeutet Thread-Sicherheit?
6.7.4Fazit
6.8Zusammenfassung
7Kompatibilität von Java-APIs
7.1Kompatibilitätsstufen
7.1.1Code-Kompatibilität
7.1.2Binäre Kompatibilität
7.1.3Funktionale Kompatibilität
Amöben-Effekt
7.2Verwandtschaftsbeziehungen
7.3Design by Contract
Änderung einer Methodenvorbedingung
Änderung einer Methodennachbedingung
Änderung einer Feldinvariante
7.4Codeänderungen
7.4.1Package-Änderungen
7.4.2Interface-Änderungen
7.4.3Klassenänderungen
7.4.4Spezialisierung von Rückgabetypen
7.4.5Generalisierung von Parametertypen
7.4.6Generics
7.4.7Ausnahmen
7.4.8Statische Methoden und Konstanten
7.5Praktische Techniken für API-Änderungen
Missbilligung
Delegation
Namenskonventionen
Defaultmethoden
Laufzeitschalter
Extension Interface
Eingebaute Versionsinformationen
7.6Test Compatibility Kit
Java Compatibility Kit
SigTest
7.7Zusammenfassung
8Grundlagen RESTful HTTP
8.1REST versus HTTP
8.2REST-Grundprinzipien
Eindeutige Identifikation von Ressourcen
Verwendung von Hypermedia
Verwendung von HTTP-Standardmethoden
Unterschiedliche Repräsentationen von Ressourcen
Statuslose Kommunikation
8.3Ressourcen – die zentralen Bausteine
Ressourcen und ihre Repräsentationen
Ressourcenkategorien
8.4HTTP-Methoden
GET
HEAD
PUT
POST
DELETE
OPTIONS
PATCH
Zusammenfassung
8.5HATEOAS
Unterschiede zu Remote Procedure Calls
Dynamischer Workflow
Affordance
Hypertext Transfer Protocol
8.6Zusammenfassung
9Techniken für Web-APIs
9.1Anwendungsbeispiel: Onlineshop
Remote Procedure Calls vermeiden
Ressourcen identifizieren
Granularität beachten
Konsistenz sicherstellen
Fachliche Transaktionen
Homepage-Ressource anbieten
Asynchrone Bearbeitung
Lesbare URIs
Auswahl der Medientypen
9.2URI-Design
Hackable
Konsistent
Kurz
Groß- und Kleinschreibung
Sonderzeichen
URIs mit IDs
9.3Medientypen
XML
JSON
Protocol Buffers
Mikroformate
Profiles
Hypermediafaktoren
X/HTML
HAL
Siren
Atom und AtomPub
Collection+JSON
UBER
9.4Fehlerbehandlung
Standardisierte HTTP-Statuscodes
Proprietäre Fehlercodes
9.5Versionierung
9.5.1Daten- und Sprachversionierung
9.5.2Kompatibilität und Perspektive
9.5.3Versionsidentifikation
Query-Parameter
Applikationsspezifischer Header
Accept-Header
URI
Datum als Versionsnummer
Softwarearchitektur
9.6Sicherheitsmechanismen
HTTP Basic Authentication
OAuth
OpenID Connect
9.7Partielle Rückgaben
Paging
Cursoring
Feldangabe
9.8GraphQL
Einführung
Alias und Strukturkontrolle
Eignung
9.9OData
Motivation
Aufbau
Eignung
9.10Zusammenfassung
10SOAP-Webservices
10.1SOAP-Grundlagen
Envelope
Header
Body
Fault
10.2WSDL-Grundlagen
10.3Entwurfsansätze und -muster
Contract First
Eindeutiger Servicevertrag
Fachliche Abstraktion
Explizite Grenze
Dokumentenorientiert
Granularität
Idempotente Nachrichten
Reservierung
10.4Versionierung
Versionsidentifikation
Strategien zur Versionierung
10.5SOAP versus REST
10.6Zusammenfassung
11Messaging
11.1Routenplanung für Lkw-Transporte (Teil 1)
11.2Message Broker
Destinationen
Datenratenbegrenzung
Push versus Pull
Callback Queues
11.3Produkte
Apache ActiveMQ
ActiveMQ Apollo
RabbitMQ
ZeroMQ
Apache Kafka
Aeron
Vergleich der Messaging-Systeme
11.4Standards und Protokolle
Java Messaging Service (JMS)
Simple Text Oriented Messaging Protocol (STOMP)
OpenWire
Message Queue Telemetry Transport (MQTT)
Advanced Message Queue Protocol (AMQP)
Extensible Messaging and Presence Protocol (XMPP)
11.5Routenplanung für Lkw-Transporte (Teil 2)
11.6Transaktionen und garantierte Nachrichtenzustellung
ActiveMQ
RabbitMQ
11.7Asynchrone Verarbeitung und REST
Polling
Callback
11.8Push Notifications
11.9Zusammenfassung
12Dokumentation. 12.1Motivation
12.2Zielgruppen unterscheiden
12.3Allgemeiner Aufbau
Übersicht
Erste Schritte
Benutzerhandbuch
Referenz
Weitere Elemente
12.4Beispiele
Snippets
Tutorials
Applikationen
Designfragmente
12.5Dokumentation von Java-APIs
Dokumentation mit Javadoc
Dokumentation von Klassen
Dokumentation von Methoden
Dokumentation von Packages
12.6Dokumentation von Web-APIs
Vertrag zuerst oder zuletzt?
apiDoc
Swagger
RESTful API Modeling Language (RAML)
Weitere Beschreibungssprachen
Markdown
Dokumentation von Datenstrukturen
Dokumentation versus Hypermedia
12.7Zusammenfassung
13Caching
13.1Anwendungsfälle
13.2Performance-Vorteil
13.3Verdrängungsstrategien
13.4Cache-Strategien für Schreibzugriffe
Durchgängiges Schreiben
Zurückkopieren
Cache-Verfehlen
13.5Cache-Topologien für Webanwendungen
13.6HTTP-Caching
Cache-Control
ETags
Expires
Last-Modified
no-cache und no-store
public und private
Content Delivery Networks
Cache-Einträge verwerfen
Eine Caching-Lösung entwickeln
13.7Zusammenfassung
14Skalierbarkeit
14.1Anwendungsfall
14.2Grundlagen
Varianten der Skalierung
Herausforderungen der Skalierung
Skalierungsfaktor
Performance, Durchsatz, Antwortzeit
14.3Load Balancing
DNS Load Balancing
Load Balancer
Algorithmen für Lastausgleichsentscheidungen
14.4Statuslose Kommunikation
Clientseitiger Zustand
Serverseitiger Zustand
Zustand in der Datenbank
14.5Skalierung von Datenbanken
CAP-Theorem
Wähle zwei aus drei
Ausfall ist keine Option
Schlussendliche Konsistenz
Transaktionen
14.6Skalierung von Messaging-Systemen
Verteilung von Task-Messages
Ausfallsicherheit durch replizierte Queues
Optimierung durch passende Routing-Topologien
Partitionierung
14.7Architekturvarianten
14.8Zusammenfassung
15Erweiterte Architekturthemen
15.1Consumer-Driven Contracts
Benutzerdefinierte Testfälle
Praktische Umsetzung mit Pact
Fazit
15.2Backends for Frontends
One-Size-fits-all
Dedizierte APIs
Fazit
15.3Vernachlässigte Frontend-Architektur
Nur das Web als Channel nutzen
Monolithische Clients
Fazit
15.4Netflix-APIs
»One size fits all« versus dedizierte API
Dynamische Endpunkte
Hystrix
Fazit
15.5Zusammenfassung
16API-Management. 16.1Überblick
16.2Funktionen einer API-Management-Plattform
16.3API-Management-Architektur
API-Gateway
API-Manager
API-Designer
API-Entwicklerportal
SDK
16.4Open-Source-Gateways
Repose
Tyk
16.5Zusammenfassung
ALiteraturverzeichnis
Fußnoten. 1 Application Programming Interfaces – eine Einführung
2 Qualitätsmerkmale
5 Grundlagen für Java-APIs
7 Kompatibilität von Java-APIs
8 Grundlagen RESTful HTTP
10 SOAP-Webservices
11 Messaging
13 Caching
15 Erweiterte Architekturthemen
16 API-Management
Index
