Web APIs – REST, GraphQL, SOAP & API-Design

Inhaltsverzeichnis

Schnellübersicht

Auf dieser Seite lernen Sie alles über Web APIs:

Definition: Was ist eine API und warum wird sie benötigt?
API-Typen: REST, GraphQL, SOAP, gRPC, Webhooks
HTTP-Methoden: GET, POST, PUT, DELETE, PATCH
Status Codes: 2xx, 3xx, 4xx, 5xx
Authentifizierung: API Keys, OAuth, JWT, Basic Auth
OpenAPI/Swagger: API-Dokumentation
Best Practices: API-Design, Versionierung, Rate Limiting
FAQ: Häufige Fragen zu Web APIs

1. Was ist eine API?

Definition

Eine API (Application Programming Interface) ist eine Schnittstelle, die es verschiedenen Softwareanwendungen ermöglicht, miteinander zu kommunizieren. Sie definiert, wie Anfragen gestellt und Antworten formatiert werden müssen, damit zwei Systeme Daten austauschen können – ohne dass sie die interne Implementierung des anderen kennen müssen.

Im Web-Kontext sind APIs meist HTTP-basierte Schnittstellen, die von Servern bereitgestellt werden. Client-Anwendungen (Webbrowser, Mobile Apps, andere Server) senden HTTP-Anfragen an definierte Endpunkte (URLs) und erhalten strukturierte Antworten (meist JSON oder XML) zurück.

Alltagsbeispiele: Wenn Sie mit Ihrem Google-Konto bei Spotify anmelden, nutzt Spotify die Google-API. Wenn Sie auf einer Wetter-App das aktuelle Wetter sehen, ruft die App eine Wetter-API ab. Wenn Sie mit Kreditkarte online bezahlen, kommuniziert der Shop mit einer Zahlungs-API (z.B. Stripe, PayPal).

Restaurant-Analogie

Stellen Sie sich ein Restaurant vor:

Sie (Client): Bestellen ein Gericht
Der Kellner (API): Nimmt Ihre Bestellung entgegen und bringt sie in die Küche
Die Küche (Server): Bereitet das Essen zu
Der Kellner (API): Bringt das fertige Gericht zu Ihnen zurück

Die API ist also der Vermittler zwischen Client und Server – sie definiert das "Menü" (verfügbare Endpunkte) und das "Bestellformular" (Anfrage-Format).

2. Die wichtigsten API-Typen

Es gibt verschiedene API-Architekturen, jede mit spezifischen Vor- und Nachteilen. Die Wahl hängt vom Use Case ab.

01

REST API

Representational State Transfer · Der Standard

Der mit Abstand häufigste API-Typ im Web. Nutzt HTTP-Methoden und URLs als Ressourcen-Identifikatoren.

Stateless (keine Sitzungen)
Ressourcen-basierte URLs
JSON als Standard-Format
HTTP-Methoden (GET, POST, PUT, DELETE)
Cache-fähig

Typische Einsatzgebiete: Web-Anwendungen, Mobile Apps, Microservices, öffentliche APIs (GitHub, Twitter, Stripe)

02

GraphQL

Query Language · Flexibel & Effizient

Von Facebook entwickelt. Client definiert exakt, welche Daten er benötigt – keine Über- oder Unterabfragen.

Ein einziger Endpunkt (/graphql)
Client wählt Felder aus
Starke Typisierung (Schema)
Echtzeit-Updates (Subscriptions)
Keine Versionierung nötig

Typische Einsatzgebiete: Komplexe Datenmodelle, Mobile Apps (geringe Datenmengen), Social Networks, E-Commerce

03

SOAP

Simple Object Access Protocol · Enterprise

Älterer, strikter Standard. Nutzt XML und hat eingebaute Sicherheits- und Transaktionsfeatures.

XML-basiert (WSDL-Definition)
WS-Security (Enterprise-Security)
ACID-Transaktionen
Strikte Verträge
Schwerer als REST

Typische Einsatzgebiete: Banken, Versicherungen, Enterprise-Systeme, Legacy-Integrationen, Regierungs-APIs

04

gRPC

Google Remote Procedure Call · Hochperformant

Von Google entwickelt. Nutzt Protocol Buffers und HTTP/2 für extrem schnelle, binäre Kommunikation.

Binäres Format (Protocol Buffers)
HTTP/2 (Multiplexing)
Code-Generierung aus .proto-Dateien
Bidirektionale Streams
10× schneller als REST/JSON

Typische Einsatzgebiete: Microservices-Kommunikation, Cloud-Infrastruktur (Kubernetes), Echtzeit-Systeme, IoT

05

Webhooks

Reverse API · Event-basiert

Keine klassische API: Server sendet automatisch HTTP-POST an Ihre URL, wenn ein bestimmtes Event eintritt.

Push-basiert (statt Pull)
Event-getriggert
Keine Polling nötig
Echtzeit-Benachrichtigungen
Oft mit REST APIs kombiniert

Typische Einsatzgebiete: Zahlungsbestätigungen (Stripe), CI/CD-Pipelines (GitHub), Chat-Integrationen (Slack), Monitoring

             Welcher API-Typ für welchen Fall?
            Standard-Webanwendung: REST (einfach, weit verbreitet)
Komplexe Datenabfragen: GraphQL (flexibel, effizient)
Enterprise/Finanzwesen: SOAP (strikte Verträge, Security)
Microservices-intern: gRPC (Performance, Typsicherheit)
Echtzeit-Benachrichtigungen: Webhooks (Event-basiert)

        

3. HTTP-Methoden (Verben)

HTTP-Methoden definieren, welche Aktion mit einer Ressource durchgeführt werden soll. In REST-APIs sind sie zentral.

GET

Ressource abrufen (lesen). Idempotent, sicher, cache-fähig.

POST

Neue Ressource erstellen. Nicht idempotent.

PUT

Ressource komplett ersetzen. Idempotent.

PATCH

Ressource teilweise aktualisieren. Nicht idempotent.

DELETE

Ressource löschen. Idempotent.

HEAD

Wie GET, aber nur Header (ohne Body).

OPTIONS

Verfügbare Methoden abfragen (CORS).

Beispiel: REST API für Benutzer

            HTTP
# Benutzer-Liste abrufen
GET https://api.beispiel.de/users

# Einzelnen Benutzer abrufen
GET https://api.beispiel.de/users/123

# Neuen Benutzer erstellen
POST https://api.beispiel.de/users
Body: {"name": "Max", "email": "max@example.com"}

# Benutzer komplett ersetzen
PUT https://api.beispiel.de/users/123
Body: {"name": "Max Mustermann", "email": "max@example.com"}

# Benutzer teilweise aktualisieren
PATCH https://api.beispiel.de/users/123
Body: {"email": "neue@email.com"}

# Benutzer löschen
DELETE https://api.beispiel.de/users/123
        

4. HTTP-Status Codes

Status Codes zeigen an, ob eine Anfrage erfolgreich war oder welcher Fehler aufgetreten ist. Sie sind in 5 Kategorien unterteilt.

Code	Name	Bedeutung	Typischer Einsatz
200	OK	Anfrage erfolgreich	GET, PUT, PATCH erfolgreich
201	Created	Ressource erstellt	POST erfolgreich
204	No Content	Erfolgreich, keine Antwort	DELETE erfolgreich
301	Moved Permanently	Ressource umgezogen	URL-Änderung
304	Not Modified	Cache noch gültig	Browser-Caching
400	Bad Request	Ungültige Anfrage	Fehlerhafte Parameter
401	Unauthorized	Nicht authentifiziert	Fehlender/ungültiger Token
403	Forbidden	Keine Berechtigung	Authentifiziert, aber nicht autorisiert
404	Not Found	Ressource nicht gefunden	URL existiert nicht
429	Too Many Requests	Rate Limit erreicht	Zu viele Anfragen
500	Internal Server Error	Server-Fehler	Unerwarteter Fehler
502	Bad Gateway	Ungültige Antwort vom Upstream	Proxy/Load Balancer Problem
503	Service Unavailable	Dienst nicht verfügbar	Server überlastet/Wartung

             Merkhilfe für Status Code Kategorien
            2xx (Success): "Alles klar!" – Anfrage erfolgreich verarbeitet
3xx (Redirection): "Woanders hingehen" – Ressource hat neue URL
4xx (Client Error): "Ihr Fehler" – Anfrage war ungültig
5xx (Server Error): "Unser Fehler" – Server-Problem

        

5. API-Authentifizierung

Die meisten APIs erfordern eine Authentifizierung, um zu prüfen, wer die Anfrage stellt und ob diese berechtigt ist.

API Keys

Einfachste Methode. Ein eindeutiger String, der bei jeder Anfrage mitgesendet wird. Oft in Header oder Query-Parameter.

GET /api/data?api_key=abc123xyz # Oder im Header: X-API-Key: abc123xyz

OAuth 2.0

Industriestandard für Drittanbieter-Zugriff. Nutzer autorisiert App, App erhält Access Token. Unterstützt Scopes (Berechtigungen).

Authorization: Bearer eyJhbGciOi...

JWT (JSON Web Token)

Self-contained Token mit Signatur. Enthält Nutzer-Infos und Ablaufdatum. Wird oft nach OAuth-Login ausgestellt.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Basic Authentication

Älteste Methode. Username:Password wird Base64-kodiert im Header mitgesendet. Nur über HTTPS!

Authorization: Basic dXNlcjpwYXNzd29yZA== # Entschlüsselt: user:password

             Sicherheitsempfehlungen
            Immer HTTPS verwenden – niemals unverschlüsselte APIs
API Keys rotieren – regelmäßig neue Keys generieren
OAuth 2.0 + JWT für moderne Anwendungen bevorzugen
Scopes nutzen – minimale Berechtigungen vergeben
Tokens nie im Code hardcoden – Umgebungsvariablen nutzen
Rate Limiting aktivieren – Missbrauch verhindern

        

6. OpenAPI & Swagger

OpenAPI (früher Swagger) ist ein Standard zur Beschreibung von REST-APIs. Es ermöglicht automatische Dokumentation und Code-Generierung.

Was ist OpenAPI?

OpenAPI ist eine YAML- oder JSON-basierte Spezifikation, die beschreibt:

Verfügbare Endpunkte (URLs)
HTTP-Methoden (GET, POST, etc.)
Anfrage- und Antwortformate
Authentifizierungsmethoden
Fehlercodes
Beispiele

Beispiel: OpenAPI-Spezifikation

            YAML
openapi: 3.0.0
info:
  title: Benutzer API
  version: 1.0.0
  description: API zur Benutzerverwaltung

paths:
  /users:
    get:
      summary: Alle Benutzer abrufen
      responses:
        '200':
          description: Erfolgreich
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    
    post:
      summary: Neuen Benutzer erstellen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Benutzer erstellt

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        

Swagger UI

Swagger UI ist ein Tool, das aus einer OpenAPI-Spezifikation eine interaktive Dokumentation generiert. Entwickler können:

Alle Endpunkte durchstöbern
Anfragen direkt im Browser testen
Code-Beispiele in verschiedenen Sprachen generieren
SDKs automatisch erstellen lassen

Beispiel: https://petstore.swagger.io

7. API Best Practices

Gute APIs sind einfach zu nutzen, gut dokumentiert, sicher und performant. Hier die wichtigsten Prinzipien.

API-Design

RESTful URLs: /users statt /getUsers
Plural Nouns: /users statt /user
Konsistente Benennung: camelCase oder snake_case durchgängig
Pagination: Große Listen paginieren (?page=1&limit=50)
Filtering: Filter-Parameter unterstützen (?status=active)
Versionierung: API-Version in URL oder Header

Sicherheit

HTTPS immer: Niemals unverschlüsselt
Authentifizierung: OAuth 2.0 + JWT bevorzugen
Rate Limiting: Anfragen pro Minute begrenzen
Input Validation: Alle Eingaben validieren
CORS: Cross-Origin-Ressourcen kontrollieren
Sensitive Data: Passwörter nie in Logs

Performance

Caching: HTTP-Cache-Header nutzen (ETag, Cache-Control)
Compression: gzip/br für Antworten aktivieren
Pagination: Große Mengen paginieren
Fields-Parameter: Nur benötigte Felder zurückgeben
Async Operations: Lange Tasks asynchron
CDN: Statische Inhalte über CDN ausliefern

Versionierung

URL-Versionierung: /v1/users (einfach, explizit)
Header-Versionierung: Accept: application/vnd.api.v1+json
Abwärtskompatibilität: Alte Versionen möglichst lange unterstützen
Deprecation Policy: Klare Ankündigung vor Removal
Changelog: Änderungen dokumentieren
Sunset Header: Sunset: Sat, 01 Jan 2025 00:00:00 GMT

             Die 10 Goldenen API-Regeln
            Dokumentation zuerst: OpenAPI-Spezifikation vor Implementierung erstellen
Konsistenz: Einheitliches Design über alle Endpunkte
Fehlerbehandlung: Klare, hilfreiche Fehlermeldungen mit Error-Codes
Idempotenz: PUT/DELETE sollten idempotent sein
HTTP-Status korrekt: 200, 201, 204, 400, 401, 403, 404, 500 richtig nutzen
Rate Limiting: Header X-RateLimit-* mitliefern
Logging: Alle Anfragen loggen (für Debugging & Security)
Testing: Automatische Tests für alle Endpunkte
Monitoring: Performance, Fehlerraten, Latenz überwachen
Feedback: Nutzer-Feedback einholen und API iterativ verbessern

        

8. FAQ – Häufige Fragen & Antworten

Häufige Fragen zu Web APIs

Was ist der Unterschied zwischen REST und GraphQL?

REST: Mehrere Endpunkte, Server bestimmt Struktur der Antwort, Over-/Underfetching möglich.

GraphQL: Ein Endpunkt, Client bestimmt exakt welche Felder, kein Overfetching, aber komplexer zu implementieren.

Wann was? REST für einfache CRUD-Operationen, GraphQL für komplexe Datenmodelle mit vielen verschachtelten Beziehungen.

Was bedeutet "idempotent" bei HTTP-Methoden?

Eine HTTP-Methode ist idempotent, wenn sie bei mehrfacher Ausführung denselben Zustand erzeugt.

Idempotent: GET, PUT, DELETE (mehrfach ausführen = gleiches Ergebnis)
Nicht idempotent: POST, PATCH (jedes Mal neuer Zustand)

Beispiel: DELETE /users/123 kann 10× aufgerufen werden – nach dem ersten Mal ist der User weg, die restlichen 9 Aufrufe ändern nichts mehr.

Warum sollte ich API-Versionierung nutzen?

APIs entwickeln sich weiter – manchmal müssen Endpunkte geändert oder entfernt werden. Ohne Versionierung würden diese Änderungen bestehende Clients brechen.

Vorteile:

Alte Clients können weiterlaufen
Neue Features können parallel eingeführt werden
Kontrollierte Migration statt Big Bang

Best Practice: Alte Versionen mindestens 1-2 Jahre weiter unterstützen, klare Deprecation-Policy kommunizieren.

Was ist CORS und warum brauche ich das?

CORS (Cross-Origin Resource Sharing) ist ein Sicherheitsmechanismus, der bestimmt, welche Domains auf Ihre API zugreifen dürfen.

Problem: Browser blockieren standardmäßig Anfragen von einer Domain (z.B. frontend.com) zu einer anderen (z.B. api.backend.com).

Lösung: API sendet CORS-Header:

Access-Control-Allow-Origin: https://frontend.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type

Wie schütze ich meine API vor Missbrauch?

Mehrschichtige Sicherheitsstrategie:

Authentifizierung: OAuth 2.0 + JWT (niemals API Keys allein für sensitive Daten)
Rate Limiting: Z.B. 100 Anfragen/Minute pro API Key
Input Validation: Alle Eingaben strikt validieren (SQL-Injection, XSS verhindern)
HTTPS: Immer verschlüsselt
WAF: Web Application Firewall für zusätzliche Filterung
Monitoring: Ungewöhnliche Muster erkennen (z.B. viele 401-Fehler)
IP-Whitelisting: Für interne APIs nur bestimmte IPs erlauben

Was ist der Unterschied zwischen PUT und PATCH?

PUT: Ersetzt die gesamte Ressource. Alle Felder müssen mitgesendet werden.

PATCH: Aktualisiert nur bestimmte Felder. Nur die geänderten Felder werden mitgesendet.

Beispiel:

PUT /users/123 mit {"name": "Max", "email": "max@example.com"} → User hat nur noch diese zwei Felder
PATCH /users/123 mit {"email": "neue@email.com"} → Nur Email wird geändert, Name bleibt

Best Practice: PATCH für Teilaktualisierungen, PUT für komplette Ersetzungen.

Wie teste ich eine API während der Entwicklung?

Verschiedene Tools verfügbar:

Postman: GUI-Tool zum manuellen Testen, Collections, Environments
Insomnia: Ähnlich Postman, leichtgewichtiger
curl: Kommandozeilen-Tool für schnelle Tests
Swagger UI: Interaktive Dokumentation zum Testen
Automated Tests: Jest, PyTest, JUnit für CI/CD
Browser DevTools: Network-Tab für Frontend-Integration

Best Practice: Automatische Tests in CI/CD-Pipeline integrieren, manuelle Tests mit Postman für Exploratory Testing.

Was ist Rate Limiting und warum ist es wichtig?

Rate Limiting begrenzt die Anzahl der Anfragen, die ein Client in einem bestimmten Zeitraum stellen darf.

Zweck:

Schutz vor Missbrauch (DDoS, Brute-Force)
Faire Ressourcenverteilung
Server-Performance stabil halten
Kosten kontrollieren (bei Cloud-APIs)

Implementierung:

Header: X-RateLimit-Limit: 100 (max. Anfragen)
Header: X-RateLimit-Remaining: 87 (verbleibend)
Header: X-RateLimit-Reset: 1640995200 (Reset-Zeitpunkt)
Status 429 bei Überschreitung

Zusammenfassung

             Die wichtigsten Punkte
            API: Schnittstelle zwischen Anwendungen – definiert Anfragen und Antworten
REST: Häufigster API-Typ, nutzt HTTP-Methoden und Ressourcen-URLs
GraphQL: Flexibel, Client wählt Felder aus, kein Overfetching
SOAP: Enterprise-Standard, XML-basiert, strikte Verträge
gRPC: Hochperformant, binär, für Microservices
Webhooks: Event-basiert, Push statt Pull
HTTP-Methoden: GET, POST, PUT, PATCH, DELETE
Status Codes: 2xx (Erfolg), 3xx (Redirect), 4xx (Client-Fehler), 5xx (Server-Fehler)
Authentifizierung: API Keys, OAuth 2.0, JWT, Basic Auth
Best Practices: Dokumentation, Versionierung, Rate Limiting, HTTPS

        

             API-Design Checkliste
            ✅ OpenAPI-Spezifikation erstellt?
✅ RESTful URLs verwendet?
✅ HTTP-Status Codes korrekt genutzt?
✅ Authentifizierung implementiert (OAuth 2.0 + JWT)?
✅ Rate Limiting aktiviert?
✅ HTTPS erzwungen?
✅ Input Validation implementiert?
✅ CORS konfiguriert?
✅ Versionierung geplant?
✅ Logging & Monitoring eingerichtet?

        

Weiterführende Themen

Authentication Web

Web-Authentifizierung im Detail – OAuth, JWT, Sessions, Cookies.

Zur Web-Authentifizierung

Performance Optimierung

Web-Performance verbessern – Caching, Lazy Loading, Code Splitting.

Zur Performance-Optimierung

Web Security

Web-Sicherheit – XSS, CSRF, SQL-Injection, HTTPS, Security Headers.

Zur Web-Security

Backend Frameworks

Backend-Frameworks – Express, Django, Spring Boot, Laravel im Vergleich.

Zu Backend-Frameworks