Einheit 5 — Anatomie eines API-Requests
Was du nach dieser Einheit weißt: Du kannst einen vollständigen API-Request in alle Bestandteile zerlegen — URL, Pfad-Parameter, Query-Parameter, Header, Body, SSL-Einstellungen — und weißt warum jedes Element existiert.
Die vollständige URL zerlegt
https://api.example.com:443/v1/customers/42/orders?status=pending&limit=10
───── ──────────────── ─── ── ──────────────────── ───────────────────────
│ │ │ │ │ │
Protokoll Host Port API- Ressourcen-Pfad Query-Parameter
Version
Protokoll: HTTP vs. HTTPS
https:// bedeutet: die Verbindung ist mit TLS verschlüsselt. Niemand der den Netzwerkverkehr mitliest kann den Inhalt der Anfrage sehen — weder den Body noch die Header noch das Authentifizierungstoken.
http:// ist unverschlüsselt. Für produktive APIs mit echten Daten niemals verwenden.
Host
Der Hostname des API-Servers. Wird über DNS in eine IP-Adresse aufgelöst.
Häufige Muster:
api.example.com— dedizierte API-Domainexample.com/api— API als Pfad der Hauptdomain192.168.1.50— direkte IP-Adresse (intern, ohne DNS)
Port
Der Standard-Port für HTTPS ist 443 — er wird in der URL normalerweise weggelassen, weil er implizit ist. Wenn eine API auf einem nicht-standardmäßigen Port läuft (z. B. 8443 oder 8080), muss er explizit angegeben werden:
https://api.internal.com:8443/v1/customers
API-Versionierung
/v1/ in der URL zeigt an, dass dies Version 1 der API ist. Wenn der Anbieter die API grundlegend ändert, veröffentlicht er /v2/ — ohne /v1/ zu brechen. Bestehende Integrationen funktionieren weiter.
Nicht alle APIs versionieren so. Manche nutzen Header-basierte Versionierung:
Accept: application/vnd.example.v2+json
Ressourcen-Pfad
/customers/42/orders
customers— die Ressourcen-Sammlung42— ein Pfad-Parameter: die ID des spezifischen Kundenorders— die Unterressource: Bestellungen dieses Kunden
Pfad-Parameter sind Teil der URL-Struktur und identifizieren eine spezifische Ressource. Sie stehen zwischen den Schrägstrichen.
Query-Parameter
?status=pending&limit=10
Query-Parameter stehen nach dem ? und sind durch & getrennt. Sie filtern, sortieren oder paginieren die zurückgegebenen Daten.
?status=pending → nur ausstehende Bestellungen
&limit=10 → maximal 10 Ergebnisse
&page=2 → zweite Seite (Paginierung)
&sort=created_at:desc → neueste zuerst
&from=2026-01-01 → ab diesem Datum
Query-Parameter verändern die Ressource nicht — sie steuern wie viel und was zurückgegeben wird.
URL-Encoding
URLs dürfen nur bestimmte Zeichen enthalten. Sonderzeichen müssen kodiert werden — das nennt sich URL-Encoding (oder Percent-Encoding).
Leerzeichen → %20 oder +
ä → %C3%A4
& → %26 (wenn im Wert, nicht als Trenner)
= → %3D (wenn im Wert, nicht als Zuweisung)
Beispiel: Wenn du nach "Müller GmbH & Co." suchen willst:
GET /customers?name=M%C3%BCller+GmbH+%26+Co.
In der Praxis übernimmt 42°OS das Encoding automatisch. Relevant wird es beim manuellen Testen oder wenn API-Fehlermeldungen auf "invalid URL" hinweisen.
Der Request-Body im Detail
Bei POST, PUT und PATCH werden die Nutzdaten im Body übertragen. Das häufigste Format ist JSON:
{
"customer_id": 42,
"items": [
{"product_id": 789, "quantity": 3, "price": 29.90},
{"product_id": 456, "quantity": 1, "price": 149.00}
],
"shipping_address": {
"street": "Musterstraße 1",
"city": "Bielefeld",
"zip": "33602"
},
"notes": "Bitte Express-Versand"
}
Der Header Content-Type: application/json teilt dem Server mit in welchem Format der Body ist.
Andere Body-Formate:
application/x-www-form-urlencoded — wie HTML-Formulare, Schlüssel=Wert-Paare:
customer_id=42&quantity=3&product_id=789
multipart/form-data — für Datei-Uploads, kombinierbares mit anderen Feldern.
application/xml — XML-Body, bei älteren APIs und SOAP.
SSL-Verifikation
Wenn dein System eine HTTPS-Verbindung aufbaut, prüft es ob das SSL-Zertifikat des Servers:
- von einer vertrauenswürdigen Zertifizierungsstelle ausgestellt wurde
- für die richtige Domain gilt
- noch nicht abgelaufen ist
Bei internen Systemen (On-Premises) werden oft selbstsignierte Zertifikate verwendet — ausgestellt vom Unternehmen selbst, nicht von einer öffentlichen CA. Diese werden von externen Systemen standardmäßig abgelehnt.
Optionen:
- Das Zertifikat der internen CA in den Trust Store des aufrufenden Systems importieren
- SSL-Verifikation deaktivieren (
ssl_verify: falseim Post Agent)
Das Deaktivieren der SSL-Verifikation ist nur für interne, vertrauenswürdige Systeme akzeptabel. Für externe APIs niemals deaktivieren — es öffnet die Verbindung für Man-in-the-Middle-Angriffe.
Paginierung
APIs geben selten alle Datensätze auf einmal zurück. Bei großen Mengen (Tausende von Bestellungen) wird die Antwort in Seiten aufgeteilt — Paginierung.
Offset-basiert:
GET /orders?limit=100&offset=0 → Einträge 1–100
GET /orders?limit=100&offset=100 → Einträge 101–200
GET /orders?limit=100&offset=200 → Einträge 201–300
Cursor-basiert (moderner):
GET /orders?limit=100
Antwort: { "data": [...], "next_cursor": "eyJpZCI6MTAwfQ" }
GET /orders?limit=100&cursor=eyJpZCI6MTAwfQ
Antwort: { "data": [...], "next_cursor": "eyJpZCI6MjAwfQ" }
Die Antwort enthält typischerweise Metadaten über die Gesamtzahl:
{
"data": [...],
"pagination": {
"total": 1847,
"page": 1,
"per_page": 100,
"total_pages": 19
}
}
In 42°OS-Workflows muss Paginierung explizit behandelt werden — typischerweise mit einer Schleife die solange weitere Seiten abruft bis next_cursor fehlt oder die letzte Seite erreicht ist.
Rate Limiting
APIs begrenzen wie viele Anfragen ein Client pro Zeiteinheit stellen darf. Das schützt vor Überlastung und Missbrauch.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711532400
Retry-After: 60
Der Header X-RateLimit-Remaining: 0 zeigt: das Kontingent ist erschöpft. Retry-After: 60 sagt: warte 60 Sekunden.
In 42°OS-Workflows: bei kritischen Integrationen Rate-Limit-Header auswerten und bei 429-Antworten automatisch warten und wiederholen.