REST und RESTful API Design Schulung: Ressourcen und HTTP

Einführung in REST und RESTful APIs

• REST als Architekturstil nach Roy Fielding – weder Protokoll noch Datenformat
• Eine RESTful API für das eigene Unternehmen: interne, Partner- und öffentliche APIs
• Reifegradmodell nach Richardson: von RPC über Ressourcen und Methoden bis Hypermedia
• Bevor Sie eine API bauen: Zweck, Konsumenten, Lebensdauer und Betriebsverantwortung klären
• Wann REST passt und wann RPC-Aufrufe oder Ereignisse die bessere Wahl sind

Wer braucht Ihre API?

• Warum gutes API-Design zählt: Entwicklererfahrung, Änderungskosten, Sicherheit
• API als Produkt: Nutzergruppen, Leistungsversprechen und Lebenszyklus
• Ansätze zum Hinzufügen einer API: design-first mit OpenAPI oder code-first
• API-Fassade vor einer Bestandsanwendung: Fachobjekte statt Datenbanktabellen nach außen
• Tipps zur Modellierung: Fachsprache der Konsumenten, Glossar, keine internen Kürzel
• Teilnehmer identifizieren: Personen, Systeme und Partner mit ihren Rollen und Rechten
• Aktivitäten ermitteln und in Schritte zerlegen: Auslöser, Vorbedingungen, Ergebnis
• Übung: Teilnehmer-Aktivitäten-Tabelle für ein Fallbeispiel erstellen

Wie sieht Ihre API aus?

• Ressourcen und Sammlungen aus den Aktivitäten ableiten und zu API-Methoden gruppieren
• URI-Design: Pluralnamen, Hierarchie, stabile IDs und keine Verben im Pfad
• Filtern, Sortieren und Paginieren: Offset oder Cursor, Navigation über den Link-Header
• Aktivitäten auf Methoden abbilden: GET, POST, PUT, PATCH und DELETE
• Sichere und idempotente Methoden; Wiederholungen von POST mit einem Idempotency-Key
• Aktionen jenseits von CRUD: Zustandsübergänge als Unterressource oder eigene Ressource
• Entwurf validieren: jede Aktivität gegen die Liste der Endpunkte durchspielen
• Entwurf als OpenAPI 3.1 beschreiben und per Mock-Server mit Prism früh testen lassen

Wie funktioniert Ihre API?

• REST und HTML: das Web als erste REST-Anwendung, Links und Formulare als Zustandsübergänge
• Anfrage und Antwort nach RFC 9110: Methode, Ziel-URI, Header und Inhalt
• Antwortcodes gezielt wählen: 200, 201, 204, 400, 401, 403, 404, 409, 422, 429 und 5xx
• Fehlerantworten einheitlich als Problem Details nach RFC 9457
• Die Einschränkungen: Client-Server, Zustandslosigkeit, Cachefähigkeit, Schichtenarchitektur
• Einheitliche Schnittstelle: Ressourcen, Repräsentationen, selbstbeschreibende Nachrichten, HATEOAS
• Code auf Anfrage: das einzige optionale Constraint und wo es heute noch vorkommt

Sicherheit: Authentifizierung und Autorisierung

• Authentifizierung: API-Schlüssel, OAuth 2.0 mit Client Credentials und Authorization Code mit PKCE
• Bearer-Tokens und JWT: Gültigkeit, Scopes und warum Tokens nie in die URL gehören
• Autorisierung auf Objektebene: Broken Object Level Authorization aus den OWASP API Security Top 10
• Missbrauch begrenzen: Rate Limiting, Statuscode 429 und Retry-After

Versionierung und Weiterentwicklung

• Bewährte Versionierungsstrategien: Pfad, Header oder Medientyp im Vergleich
• Abwärtskompatible Änderungen und Breaking Changes unterscheiden, Tolerant Reader auf Clientseite
• Abkündigung ankündigen mit den Headern Deprecation und Sunset
• Einen API-Styleguide fürs Unternehmen aufsetzen, etwa auf Basis veröffentlichter Leitfäden

Inhalte, Hypermedia und Caching

• Medientypen auswählen: application/json, eigene Medientypen, Formulare und Datei-Uploads
• Inhalte robust verarbeiten: Datumsangaben, Geldbeträge, IDs und unbekannte Felder
• Hypermedia-Ansätze: HAL, JSON:API und Siren im Vergleich
• Inhaltsaushandlung mit Accept, Content-Type und Accept-Language
• HTTP-Caching nach RFC 9111: Cache-Control, ETag und bedingte Anfragen
• Konkurrierende Änderungen verhindern: If-Match und 412 Precondition Failed

Dokumentation und SDKs

• Ansätze zur Dokumentation: Referenz, Einstiegsanleitung, Beispiele und Änderungsprotokoll
• Referenzdokumentation aus OpenAPI erzeugen, etwa mit Swagger UI, Redoc oder Scalar
• SDKs generieren mit OpenAPI Generator oder von Hand schreiben – Kriterien für die Wahl
• Überlegungen zum SDK-Design: Wiederholungen, Paginierung, Fehlerklassen und eigene Versionierung

RESTful APIs design-first mit Coding-Agenten

• Implementierung durch den Agenten startet erst, wenn das OpenAPI-Dokument im Review abgenommen ist
• Spectral-Regelsatz mit Hausregeln (Pluralnamen, Problem Details, Paginierung) nach jeder Spec-Änderung ausführen
• oasdiff im Pull Request: inkompatible Änderungen an Pfaden, Pflichtfeldern und Codes blockieren
• Contract-Tests mit Schemathesis aus der Spec erzeugen; Fehlerfälle wie 404, 409 und 422 ausdrücklich einfordern
• Eindeutige operationIds und Beschreibungen, damit Sprachmodelle die API als Werkzeug richtig aufrufen

Praxisprojekt: Buchungs-API für Räume eines Coworking-Spaces

• Teilnehmer und Aktivitäten erheben, Ressourcen für Räume, Buchungen und Mitglieder ableiten
• OpenAPI-Dokument mit Paginierung, Problem Details und OAuth-Scopes schreiben und linten
• Doppelbuchungen per 409 und If-Match abfangen, Verhalten am Mock-Server mit curl prüfen
• Version 2 mit Breaking Change planen, per Sunset ankündigen und Dokumentation veröffentlichen