APIs: Verträge, Identitäten und verteilte Fehlergrenzen

Eine Application Programming Interface ist eine Vertrags- und Vertrauensgrenze zwischen unabhängig betriebenen Komponenten. Der Vertrag legt fest, welche Operationen und Daten existieren; die Laufzeit entscheidet über Transport, Identität, Autorisierung, Zeitverhalten und Fehler. Für Admins ist diese Trennung zentral: Ein syntaktisch gültiger JSON-Request kann am falschen Tenant landen, mit einem gültigen Token am falschen Audience scheitern oder nach einem Clienttimeout serverseitig trotzdem erfolgreich ausgeführt worden sein.

APIs liegen in Messagingumgebungen überall: zwischen Verwaltungsclient und Mailplattform, Gateway und Verzeichnis, Monitoring und Telemetrie-Backend, Cloudanwendung und Webhook-Empfänger. Eine GUI kann dieselbe Schnittstelle verwenden, bildet aber meist nur einen Teil ihrer Zustände und Fehler ab. Belastbarer Betrieb beginnt deshalb nicht beim einzelnen curl-Aufruf, sondern bei Schnittstellenstil, Vertrag, Ressourcenmodell, Identität, Zustandsübergängen und Recoverysemantik.

Die Erklärung folgt einem API-Aufruf vom Client bis zur fachlichen Antwort. Zuerst geht es um Transport und Vertrag, danach um Identität, Fehlerbehandlung und Ereignisse; erst anschliessend folgen Gatewaybetrieb, Sicherheit und Diagnose.

Einordnung als verteiltes System

Eine Netzwerk-API ist nicht nur Anwendungscode. Ein typischer Aufruf durchläuft:

1. Clientbibliothek, CLI oder Automationsprozess;
2. Namensauflösung, Routing und Verbindungsaufbau;
3. TLS, Proxy oder Service Mesh;
4. Load Balancer, API Gateway oder Reverse Proxy;
5. Authentisierung, Tokenprüfung und Autorisierung;
6. Anwendungsdienst, Cache, Queue und Datenbank;
7. Antwortpfad, Serialisierung und Clientauswertung.

Roy Fieldings Architekturarbeit unterscheidet netzwerkbasierte Systeme ausdrücklich von transparenter lokaler Ausführung: Netzwerkkommunikation hat eigene Latenz, Kosten und Fehlermodi. Ein Architekturstil ist dabei ein koordiniertes Set von Constraints, das bestimmte Eigenschaften und Trade-offs hervorruft (Fielding – Network-based Application Architectures, Fielding – Network-based Architectural Styles).

Der relevante Stack wird je Integration dokumentiert:

REST ist ein Architekturstil, kein Datenformat

REST bezeichnet die von Fielding beschriebenen Constraints für verteilte Hypermedia-Systeme: Client/Server, Statelessness, Cache, einheitliche Schnittstelle, Layering und optional Code-on-Demand. Zur einheitlichen Schnittstelle gehören Ressourcenidentifikation, Manipulation durch Repräsentationen, selbstbeschreibende Nachrichten und Hypermedia als Zustandsmaschine. Die Standardisierung der Schnittstelle verbessert Sichtbarkeit und unabhängige Entwicklung, kann aber gegenüber spezialisierten Protokollen ineffizienter sein (Fielding – Representational State Transfer).

Eine HTTP-API mit JSON und Pfaden wie /v1/getUser ist daher nicht automatisch REST. Sie kann schlicht RPC über HTTP sein. Das ist nicht grundsätzlich schlecht; problematisch wird es, wenn Betreiber Eigenschaften erwarten, die der tatsächliche Stil nicht bietet. Beispielsweise kann ein Client einen POST nicht sicher wiederholen, nur weil der Endpoint «REST» genannt wird.

URI, Ressource und Repräsentation

Eine URI identifiziert eine Ressource; sie garantiert weder Erreichbarkeit noch eine bestimmte Operation. RFC 3986 trennt Identifikation ausdrücklich von Interaktion. Scheme, Authority, Path, Query und Fragment haben definierte Syntax, während die konkrete API ihre Ressourcensemantik festlegt (RFC 3986 – URI Generic Syntax).

Eine Ressource ist nicht ihre JSON-Datei. Dieselbe Ressource kann je Accept-Header als JSON, XML oder anderes Format repräsentiert werden. Content-Type beschreibt den gesendeten Body, Accept die bevorzugte Antwort. Status, Felder und Body bilden gemeinsam die Nachricht; nur den JSON-Body zu loggen lässt wichtige Diagnoseinformation verschwinden.

HTTP-Semantik: Methode vor Pfadname

RFC 9110 trennt Ressourcenidentifikation von Requestsemantik. Die Methode definiert die beabsichtigte Operation; der URI-Pfad allein nicht. «Safe» bedeutet, dass der Client keine Zustandsänderung beabsichtigt. «Idempotent» bedeutet, dass mehrere identische Requests dieselbe beabsichtigte Wirkung wie ein Request haben; Nebenwirkungen wie Logging dürfen trotzdem mehrfach auftreten (RFC 9110 – HTTP Semantics).

Idempotenz beschreibt die beabsichtigte Serverwirkung, nicht die Transportantwort. Ein PUT kann auf dem Server abgeschlossen sein, während die Antwort verloren geht. Ein erneuter PUT ist dann semantisch vertretbar; ein erneuter POST kann ein zweites Objekt oder eine zweite Nachricht erzeugen. Für nicht-idempotente Operationen sind ein vom Client erzeugter Operation-Identifier, ein herstellerspezifischer Idempotency-Key oder ein anschliessender Statuslookup nötig.

Statuscodes sind Kategorien, keine vollständige Diagnose

• 2xx: Request wurde in der durch den Status definierten Weise verarbeitet; nicht jeder 202 Accepted ist bereits fachlich abgeschlossen.
• 3xx: weitere Aktion oder andere Repräsentation; Redirects können Methode und Credentialfluss verändern.
• 400: Request ist aus Sicht des Servers fehlerhaft.
• 401: fehlende oder ungültige Authentisierungscredentials; die Antwort verwendet grundsätzlich WWW-Authenticate.
• 403: Server versteht den Request, verweigert ihn aber.
• 404: Ressource nicht gefunden oder absichtlich verborgen; kein sicherer Beweis ihrer Nichtexistenz.
• 409: Konflikt mit dem aktuellen Zustand.
• 412: Precondition wie If-Match nicht erfüllt.
• 429: zu viele Requests in einem Zeitfenster; Retry-After kann eine Wartezeit nennen.
• 5xx: Server konnte einen grundsätzlich gültigen Request nicht erfüllen; nicht automatisch retrybar.

RFC 6585 definiert 429 Too Many Requests, aber weder den Quotascope noch den Zähler. Diese können pro Credential, Benutzer, Tenant, Ressource, Region oder Cluster gelten (RFC 6585 – Additional HTTP Status Codes). Der Client speichert daher Status, relevante Responsefelder, Request-ID und gekürzten Fehlerbody.

Transportvarianten und Verbindungskosten

HTTP-Semantik ist von der konkreten Wire-Version getrennt. HTTP/1.1 verwendet textuelle Nachrichtenframingregeln, HTTP/2 multiplexte Streams und binäres Framing, HTTP/3 bildet HTTP auf QUIC ab. Ein API-Gateway kann clientseitig HTTP/2 annehmen und zum Backend HTTP/1.1 sprechen; das Protokoll am Client beweist nicht den vollständigen Backendpfad (RFC 9112 – HTTP/1.1, RFC 9113 – HTTP/2, RFC 9114 – HTTP/3).

Admins beobachten nicht nur Requestlatenz, sondern DNS- und Connectzeit, TLS-Handshake, Connection Reuse, HTTP-Version/ALPN, Proxy-/Gatewayzeit, Time to First Byte, Bodytransfer, Retryzahl und die gesamte Wall-Clock-Dauer.

Namens-, TCP- und TLS-Pfad prüfen

Resolve-DnsName und dig prüfen DNS. Test-NetConnection und nc prüfen TCP. openssl s_client zeigt TLS-Handshake, Zertifikatspfad und ALPN; keiner dieser Tests beweist eine erfolgreiche API-Autorisierung.

Resolve-DnsName api.example.ch -Type A
Resolve-DnsName api.example.ch -Type AAAA
Test-NetConnection api.example.ch -Port 443 -InformationLevel Detailed
curl.exe -sSvk --http2 -o NUL $env:API_HEALTH_ENDPOINT

dig api.example.ch A
dig api.example.ch AAAA
nc -vz api.example.ch 443
openssl s_client -connect api.example.ch:443 -servername api.example.ch -alpn h2,http/1.1 </dev/null

Caching und Read-after-write

HTTP-Caching speichert Repräsentationen anhand von Cachekeys und Direktiven. Cache-Control, Vary, Validators und Authentisierungsregeln bestimmen, ob und wie wiederverwendet wird. Ein 200 kann aus einem Cache stammen; ein nach PUT unmittelbar folgender GET kann je Architektur noch alten Zustand sehen (RFC 9111 – HTTP Caching).

Adminfragen:

• Liegt ein Browser-, Proxy-, CDN-, Gateway- oder Anwendungscache im Pfad?
• Welche Header bilden den Cachekey, besonders Authorization und Tenant?
• Ist die Repräsentation privat, öffentlich oder gar nicht cachebar?
• Wie lange sind negative Antworten cachebar?
• Gibt es Read-your-writes oder eventual consistency?
• Welche Region/Replik liest der nachfolgende GET?
• Ist ETag eine Inhaltsversion oder nur ein Cachevalidator?

Cachebereinigung ist keine universelle Reparatur. Sie kann Lastspitzen erzeugen und die eigentliche Inkonsistenz verdecken.

Rate Limits, Quotas und Sättigung

Rate Limit, Quota und Concurrency Limit sind verschiedene Kontrollen:

• Rate: Requests oder Kostenpunkte pro Zeitfenster.
• Quota: Gesamtverbrauch pro Tag, Monat oder Subscription.
• Concurrency: gleichzeitig laufende Requests/Streams.
• Payloadlimit: Body-, Objekt-, Batch- oder Antwortgrösse.
• Komplexitätslimit: Querytiefe, GraphQL Cost oder expandierte Beziehungen.

429 kann Retry-After liefern, aber herstellerspezifische Rate-Limit-Header sind nicht einheitlich. Der Client behandelt dokumentierte Felder als Teil des konkreten Vertrags, nicht als universellen Standard. Er begrenzt lokal die Abfragerate, verteilt Budget zwischen Workloads und speichert Scope, Restbudget und Resetzeit.

Throttling ist ein Schutzsignal, kein normaler Durchsatzmodus. Dauerhafte 429-Wellen weisen auf ungeeignete Pagination, fehlendes Caching, zu hohe Parallelität oder unzureichende Kapazität hin.

Fehlerkörper und Korrelation

Ein HTTP-Status ist zu grob für fachliche Automatisierung. RFC 9457 definiert Problem Details mit stabiler type-URI, title, status, detail und instance sowie Erweiterungsfeldern. Der Problemtyp ist die maschinenlesbare Identität; frei formulierter Text ist nicht für Parser bestimmt (RFC 9457 – Problem Details for HTTP APIs).

Ein guter Fehlervertrag liefert stabilen Fehler-/Problemtyp, HTTP-/RPC-Status, sichere Detailangabe, betroffene Feldpfade, Request-/Correlation-ID, Retrybarkeit und einen Dokumentationslink. Der Client loggt keine vollständigen Tokens, Authorization Header oder vertraulichen Payloads.

Fehlerantwort mit Headern erfassen

try {
  Invoke-WebRequest -Uri $env:API_ENDPOINT -Headers @{
    Authorization = "Bearer $env:API_TOKEN"
    Accept = 'application/problem+json, application/json'
  } -ErrorAction Stop
}
catch {
  $http = $_.Exception.Response
  [pscustomobject]@{
    Status = [int]$http.StatusCode
    RequestId = $http.Headers['x-request-id']
    RetryAfter = $http.Headers['Retry-After']
    Body = $_.ErrorDetails.Message
  }
}

curl --silent --show-error --fail-with-body \
  --dump-header error.headers --output error.json \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Accept: application/problem+json, application/json' \
  "$API_ENDPOINT"
grep -Ei '^(HTTP/|x-request-id:|retry-after:)' error.headers
jq '{type,title,status,detail,instance}' error.json

RPC, GraphQL und gRPC

Nicht jede API passt zum Ressourcenstil.

Die GraphQL-Spezifikation definiert Sprache, Typsystem, Validierung und Ausführung; Transport, Authentisierung, Rate Limit und betriebliche Querykosten sind zusätzliche Verträge (GraphQL Specification). Feldfehler können zusammen mit partiellen Daten auftreten; ein HTTPstatus allein beschreibt das Ergebnis nicht.

gRPC bildet Channels, RPCs und length-prefixed Messages auf HTTP/2-Streams ab. Der gRPC-Status wird in Trailers übertragen und ist vom HTTPstatus zu unterscheiden. Calls sind nicht automatisch idempotent; Deadline, Cancellation und Retry Policy werden pro Service verstanden (gRPC – What is gRPC?, gRPC over HTTP/2 protocol). Protocol Buffers liefern ein Interface- und Serialisierungsmodell; Feldnummern sind Kompatibilitätsanker und dürfen nach Entfernung nicht für eine andere Bedeutung wiederverwendet werden (Protocol Buffers – Language Guide).

grpcurl kann Server Reflection oder lokale Deskriptoren verwenden, um gRPC-Dienste zu untersuchen. Reflection ist selbst eine exponierte Oberfläche und wird nicht ungeprüft öffentlich freigeschaltet.

grpcurl.exe -cacert $env:GRPC_CA -H "authorization: Bearer $env:API_TOKEN" $env:GRPC_TARGET list
grpcurl.exe -cacert $env:GRPC_CA -H "authorization: Bearer $env:API_TOKEN" $env:GRPC_TARGET describe $env:GRPC_SERVICE

grpcurl -cacert "$GRPC_CA" \
  -H "authorization: Bearer $API_TOKEN" "$GRPC_TARGET" list
grpcurl -cacert "$GRPC_CA" \
  -H "authorization: Bearer $API_TOKEN" "$GRPC_TARGET" describe "$GRPC_SERVICE"

Repräsentationen: JSON ist Syntax, Schema ist Vertrag

RFC 8259 definiert JSON als Austauschformat mit Objekten, Arrays, Zahlen, Strings, Booleans und null. JSON definiert nicht, welches Feld eine stabile ID ist, ob ein fehlendes Feld und null dasselbe bedeuten, welche Zeitzone ein Timestamp hat oder ob unbekannte Eigenschaften toleriert werden (RFC 8259 – JSON).

Diese Semantik gehört in ein Schema und die Vertragsdokumentation:

• Feldname, Typ, Format und Einheit;
• required, optional, nullable und Default;
• read-only/write-only und servergeneriert;
• Enumwerte und Verhalten bei unbekannten Werten;
• Zeitformat, Zeitzone und Präzision;
• stabile ID gegenüber Anzeigename;
• Referenz-, Einbettungs- und Löschsemantik;
• Kompatibilitätsregel bei neuen oder entfernten Feldern.

JSON Schema definiert Vokabulare zur Validierung von JSON-Instanzen. Ein Schema kann Struktur prüfen, ersetzt aber keine fachlichen Invarianten oder Autorisierung (JSON Schema – Specification). Die OpenAPI Specification kann HTTP-Operationen, Parameter, Request/Response-Schemas und Security Schemes maschinenlesbar beschreiben; sie beweist nicht, dass die laufende Implementierung dem Dokument entspricht (OpenAPI Specification).

Antwort und Felder ohne GUI inspizieren

Invoke-RestMethod deserialisiert strukturierte Antworten; Invoke-WebRequest gibt mehr HTTPdetails zurück. curl zeigt Request/Response und Timing, jq filtert JSON.

$response = Invoke-WebRequest -Uri $env:API_ENDPOINT -Headers @{
  Accept = 'application/json'
  Authorization = "Bearer $env:API_TOKEN"
}
[pscustomobject]@{
  Status = [int]$response.StatusCode
  ContentType = $response.Headers['Content-Type']
  ETag = $response.Headers['ETag']
  RequestId = $response.Headers['x-request-id']
}
$response.Content | ConvertFrom-Json | ConvertTo-Json -Depth 20

curl --silent --show-error --dump-header response.headers \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $API_TOKEN" \
  "$API_ENDPOINT" |
  jq .
grep -Ei '^(HTTP/|content-type:|etag:|x-request-id:)' response.headers

Verträge und Contract Drift

Ein vollständiger API-Vertrag umfasst mehr als Happy-Path-Schemas:

Contract Drift entsteht, wenn Dokument, SDK und produktive Implementierung auseinanderlaufen. Deshalb wird die veröffentlichte Spezifikation als versioniertes Artefakt gespeichert, in CI validiert und gegen eine reale Testumgebung geprüft. Generated Clients reduzieren Tipparbeit, übertragen aber auch Fehler und Breaking Changes des Schemas in viele Consumer.

Consumer-driven Tests können Annahmen eines Clients sichtbar machen. Sie ersetzen nicht die Providersemantik: Ein Mock kann einen 200 liefern, obwohl Produktion nach einem Gatewayupdate einen anderen Header, eine andere Pagination oder ein neues Enum zurückgibt.

Bis hierhin war der Aufruf technisch gültig. Ob er auch von der richtigen Identität für das richtige Objekt ausgeführt werden darf, entscheidet die Sicherheitsprüfung.

Authentisierung ist nicht Autorisierung

Ein API-Key oder Token beantwortet zunächst, welcher Client oder Principal spricht. Autorisierung entscheidet anschliessend, welche Aktion auf welcher Ressource in welchem Scope erlaubt ist. Ein gültiger Token kann deshalb korrekt mit 403 abgewiesen werden.

OAuth 2.0 definiert Rollen und Grantmechanismen zur Ausstellung von Access Tokens; Bearer Tokens können von jedem verwendet werden, der sie besitzt (RFC 6749 – OAuth 2.0, RFC 6750 – Bearer Token Usage). Die Security BCP RFC 9700 fordert minimale Privilegien, Audience Restriction und Schutz von Redirectflows; sie verbietet den Resource Owner Password Credentials Grant. Für Replay-Schutz nennt sie sendergebundene Tokens über mTLS oder DPoP (RFC 9700 – OAuth 2.0 Security BCP, RFC 8705 – OAuth mTLS, RFC 9449 – DPoP).

OpenID Connect legt eine Identitätsschicht auf OAuth; ein ID Token ist für den Client und nicht automatisch ein Access Token für eine API (OpenID Connect Core). Ein JWT ist lediglich ein kompaktes Claimformat. Signaturprüfung allein genügt nicht: Algorithmus, Issuer, Audience, Zeitclaims, Keyauswahl und anwendungsspezifische Claims müssen validiert werden (RFC 7519 – JSON Web Token, RFC 8725 – JWT Best Current Practices).

Workload-Token beziehen und API aufrufen

Der Client-Credentials-Flow eignet sich nur, wenn die Anwendung in eigenem Namen handelt und ihr Credential sicher halten kann. Secret, Zertifikat oder föderierte Workloadidentität, Tokenendpoint, Audience/Resource und Scope gehören in die konkrete Plattformdokumentation.

$token = Invoke-RestMethod -Method Post -Uri $env:TOKEN_ENDPOINT -Body @{
  grant_type = 'client_credentials'
  client_id = $env:CLIENT_ID
  client_secret = $env:CLIENT_SECRET
  scope = $env:API_SCOPE
}
Invoke-RestMethod -Uri $env:API_ENDPOINT -Headers @{
  Authorization = "Bearer $($token.access_token)"
  Accept = 'application/json'
}

API_TOKEN="$(curl --silent --show-error --fail \
  --request POST "$TOKEN_ENDPOINT" \
  --data-urlencode grant_type=client_credentials \
  --data-urlencode client_id="$CLIENT_ID" \
  --data-urlencode client_secret="$CLIENT_SECRET" \
  --data-urlencode scope="$API_SCOPE" |
  jq --raw-output .access_token)"
curl --silent --show-error --fail \
  --header "Authorization: Bearer $API_TOKEN" \
  --header 'Accept: application/json' "$API_ENDPOINT" | jq .

Secrets erscheinen weder in der Kommandozeile noch im Transcript oder Debuglog. Das Beispiel zeigt den Protokollfluss, nicht einen geeigneten Secrettransport für Produktionsprozesse.

API Gateway und Vertrauensgrenzen

Ein Gateway kann TLS terminieren, Token validieren, Routing, Quotas, Schemafilter, WAF-Regeln und Observability bündeln. Es ist damit Kontrollpunkt und Ausfallbereich. Der Backenddienst darf nicht still voraussetzen, dass jeder Request über genau diesen Gatewaypfad kam.

• Client → Gateway: öffentliche Hostidentität, TLS, DDoS/Quota, Clientcredential.
• Gateway → Service: eigene mTLS- oder Workloadidentität; keine blinde Vertrauensannahme aus Quell-IP.
• Identity Provider → Validator: Issuer Metadata, JWKS, Keyrotation, Cache und Uhr.
• Service → Datenhaltung: fachliche Autorisierung und Mandantengrenze.
• Webhookprovider → Receiver: Signatur, Zeitfenster, Event-ID und Replayprüfung.

RFC 9700 warnt bei Reverse Proxies ausdrücklich vor ungeprüften eingehenden Forwarding-Headern. Der Proxy muss sicherheitsrelevante Felder bereinigen; der interne Link muss gegen Mithören, Injection und Replay geschützt sein (RFC 9700 – OAuth 2.0 Security BCP).

Der Gatewaystatus 200 beweist nicht, dass eine nachgelagerte Queue oder Replikation gesund ist. Umgekehrt kann ein Backend gesund sein, während DNS, Zertifikat, Tokenvalidator oder Quota jeden Client blockieren.

Nach Gateway und Berechtigungsprüfung bleibt die schwierigste Betriebsfrage: Was ist passiert, wenn der Client keine rechtzeitige Antwort erhält? Ein Timeout beweist nicht, dass der Server nichts geändert hat.

Timeouts, Deadlines und partielle Ausführung

«Timeout» ist kein Serverresultat. Der Client weiss nur, dass innerhalb seiner Frist keine verwertbare Antwort angekommen ist. Der Request kann vor dem Verbindungsaufbau gescheitert, am Gateway verworfen, im Dienst noch aktiv oder bereits committed sein, während nur die Antwort verlorenging.

Jede Schicht kann eine eigene Frist besitzen: DNS, Connect, TLS, Clientgesamtzeit, Proxy, Gateway, Upstream, Datenbank und Queue. Die äussere Deadline muss mit den inneren Fristen abgestimmt sein; sonst bricht der Client nach 30 Sekunden ab, während der Server 60 Sekunden weiterarbeitet und ein Retry parallel dieselbe Aktion startet.

Ein Dienst propagiert nach Möglichkeit eine verbleibende Deadline statt für jeden Hop die volle Zeit neu zu starten. Cancellation ist best effort: Sie beweist nicht, dass ein bereits commiteter Seiteneffekt rückgängig gemacht wurde.

Retries, Backoff und Idempotenz

Automatische Wiederholung ist nur zulässig, wenn Fehlerklasse und Operation es erlauben. Ein robuster Client klärt:

1. Wurde überhaupt eine Verbindung hergestellt?
2. Ist ein Status oder ein Protokollfehler vorhanden?
3. Ist die Operation safe/idempotent oder mit Deduplizierung geschützt?
4. Gibt der Server Retry-After oder eine produktspezifische Backoffangabe?
5. Bleibt genügend End-to-End-Deadline?
6. Vergrössert ein Retry eine Überlastung?

Exponential Backoff mit Jitter verhindert synchrone Retrywellen. Die Zahl der Versuche ist begrenzt und Teil der Gesamtlatenz. 401 oder 403 werden nicht durch häufigere Wiederholung repariert; 429 verlangt Quotarespekt; ein 500 nach einem POST kann trotz Fehlerbody einen partiellen Seiteneffekt hinterlassen.

Für eine fachliche Operation speichert der Client eine stabile Operation-ID. Der Server hält Ergebnis oder Deduplizierungsstatus mindestens so lange wie das maximale Retryfenster. Fehlt eine solche Zusage, liest der Client vor dem Retry anhand einer stabilen Objekt-ID oder Suchbedingung nach.

Optimistische Nebenläufigkeit

Read-modify-write ohne Versionsbedingung erzeugt Lost Updates:

Client A liest Version 7     Client B liest Version 7
Client A schreibt Änderung  → Version 8
Client B schreibt alten Stand plus Änderung → A geht verloren

HTTP unterstützt bedingte Requests mit Validators wie ETag. Der Client liest den ETag und sendet bei der Änderung If-Match; hat sich die Repräsentation geändert, antwortet der Server mit 412 Precondition Failed statt einen fremden Stand zu überschreiben. Die konkrete API muss dokumentieren, ob der ETag stark genug für diese Semantik ist (RFC 9110 – HTTP Semantics).

$read = Invoke-WebRequest -Uri $env:OBJECT_ENDPOINT -Headers @{
  Authorization = "Bearer $env:API_TOKEN"
}
$body = $read.Content | ConvertFrom-Json
$body.enabled = $false
Invoke-RestMethod -Method Put -Uri $env:OBJECT_ENDPOINT -Headers @{
  Authorization = "Bearer $env:API_TOKEN"
  'If-Match' = $read.Headers['ETag']
} -ContentType 'application/json' -Body ($body | ConvertTo-Json -Depth 20)

ETAG="$(curl --silent --show-error --dump-header headers.txt \
  --header "Authorization: Bearer $API_TOKEN" \
  --output object.json "$OBJECT_ENDPOINT" &&
  grep -i '^etag:' headers.txt | cut -d' ' -f2- | tr -d '\\r')"
jq '.enabled = false' object.json > object.updated.json
curl --silent --show-error --fail-with-body \
  --request PUT --header "Authorization: Bearer $API_TOKEN" \
  --header "If-Match: $ETAG" --header 'Content-Type: application/json' \
  --data-binary @object.updated.json "$OBJECT_ENDPOINT"

Pagination, Filter und konsistente Mengen

Ein Endpoint, der heute 50 Objekte liefert, kann morgen 50’000 liefern. Pagination ist Teil des Vertrags:

• Offset/Page: einfach, aber Einfügungen und Löschungen können Dubletten oder Lücken erzeugen.
• Cursor/Continuation Token: kodiert serverseitigen Fortschritt; Token ist opak und wird nicht interpretiert.
• Keyset: sortiert nach stabiler, eindeutiger Fortsetzungs-ID.
• Snapshot: hält eine konsistente Sicht über mehrere Seiten, benötigt aber Serverzustand oder Versionsanker.

Der Client folgt dem dokumentierten Next-Link oder Cursor und konstruiert ihn nicht aus Vermutungen. RFC 8288 definiert typisierte Links, jedoch keine universelle Pagination; konkrete Relation und Bodyform bleiben API-Vertrag (RFC 8288 – Web Linking).

Filter und Sortierung müssen über Seiten stabil sein. Eine Sortierung nur nach nicht-eindeutigem Zeitstempel ist unzureichend; ein tie-breaker wie unveränderliche ID gehört dazu. Bei Delta-/Change-APIs werden Cursor, Ablauf und Resynchronisationspfad dokumentiert.

$next = $env:COLLECTION_ENDPOINT
$items = while ($next) {
  $page = Invoke-RestMethod -Uri $next -Headers @{
    Authorization = "Bearer $env:API_TOKEN"
  }
  $page.value
  $next = $page.nextLink
}
$items | Sort-Object id -Unique | Export-Csv .\\api-items.csv -NoTypeInformation

next="$COLLECTION_ENDPOINT"
while [ -n "$next" ]; do
  page="$(curl --silent --show-error --fail \
    --header "Authorization: Bearer $API_TOKEN" "$next")" || exit 1
  printf '%s\\n' "$page" | jq -c '.value[]'
  next="$(printf '%s\\n' "$page" | jq -r '.nextLink // empty')"
done

Webhooks, Events und asynchrone APIs

Ein synchroner HTTP-Erfolg und eine fachlich abgeschlossene Verarbeitung sind verschiedene Zustände. Ein 202 Accepted bestätigt nach RFC 9110 nur, dass der Server die Verarbeitung angenommen hat; der Auftrag kann später noch scheitern. Ein Webhook-Empfänger bestätigt umgekehrt häufig lediglich die persistierte Annahme eines Events. Wer 2xx mit «Geschäftsvorgang abgeschlossen» gleichsetzt, verliert genau jene Zwischenzustände, die bei Queues, Retries und Teilstörungen relevant sind (RFC 9110 – HTTP Semantics).

Ein betrieblich brauchbares Event enthält mindestens eine stabile Event-ID, Ereignistyp und Schemaversion, Erzeugungszeit, Produzent, Ressourcen-ID sowie – falls die Reihenfolge fachlich zählt – eine Ressourcen- oder Sequenzversion. CloudEvents standardisiert dafür einen herstellerneutralen Eventumschlag; AsyncAPI beschreibt Nachrichtenkanäle und Operationen maschinenlesbar, ähnlich der Rolle von OpenAPI für Request/Response-APIs (CloudEvents Specification, AsyncAPI Specification).

Webhooks werden wie ein fremder, wiederholender Client betrieben:

• Der Sender signiert den unveränderten Request-Body zusammen mit Zeit- oder Nonce-Metadaten; der Empfänger validiert Signatur, akzeptiertes Zeitfenster und Zielkontext vor dem Parsen. Standardisierte HTTP Message Signatures können Komponenten und abgeleitete Felder kryptografisch binden (RFC 9421 – HTTP Message Signatures).
• Der Empfänger dedupliziert über Event-ID und speichert Annahme vor der positiven Bestätigung. Verarbeitung wird idempotent entworfen.
• Retries besitzen begrenzte Laufzeit, Backoff und eine Dead-Letter- oder Quarantänestrecke. Ein Replay ist protokolliert und erzeugt keine neue fachliche Identität.
• Ein periodischer Reconciliation-Lauf vergleicht Quellsystem und lokalen Zustand. Webhooks sind Beschleuniger, nicht zwingend die einzige Quelle der Wahrheit.

API-Sicherheit: Objekt, Funktion und Datenfluss

Eine bestandene Tokenprüfung beantwortet nur, wer beziehungsweise welcher Workload spricht und für welche Audience das Credential gedacht ist. Die Anwendung muss für jedes Objekt und jede Operation zusätzlich entscheiden, ob diese Identität genau diesen Mandanten, Benutzer, Schlüssel oder Nachrichtenbestand lesen oder verändern darf. Die OWASP API Security Top 10 hebt deshalb unter anderem Broken Object Level Authorization, Broken Authentication, unbeschränkten Ressourcenverbrauch, SSRF und fehlerhaftes API-Inventar als eigene Risikoklassen hervor (OWASP API Security Top 10).

Für Infrastruktur-APIs folgen daraus konkrete Kontrollen:

• Objektbezug: Tenant- und Objektanker kommen aus serverseitig validiertem Kontext, nicht allein aus einem frei wählbaren Pfad- oder Bodyfeld.
• Eingangsgrenzen: Content-Type, Schema, Feldlängen, Verschachtelung, Gesamtgrösse, Kompressionsverhältnis und Verarbeitungszeit sind begrenzt.
• Ausgehende Verbindungen: URLs aus Requests oder Webhooks passieren Allowlist, DNS-/IP-Prüfung und Egress-Policy; Redirects werden erneut geprüft.
• Credentials: Tokens erscheinen weder in URI noch Log; Secrets werden rotiert, auf Ziel-Audience und minimale Scopes beschränkt und nicht in Clientartefakte eingebettet.
• Trust Hops: Terminiert ein Gateway TLS, muss der Backend-Hop separat authentisiert und autorisiert werden. Ein vertrauenswürdiger Forwarded-Header entsteht nur an einer kontrollierten Proxygrenze.
• Audit: privilegierte Änderungen protokollieren Client, Principal, Zielobjekt, Aktion, Vorher/Nachher-Referenz, Request-ID und Ergebnis – ohne Secret oder vollständigen sensitiven Payload.

OAuth 2.0 Security Best Current Practice rät unter anderem vom Resource Owner Password Credentials Grant ab, verlangt exakte Redirect-URI-Vergleiche und bevorzugt sendergebundene beziehungsweise kurzlebige Tokens, wo das Bedrohungsmodell dies erfordert (RFC 9700 – Best Current Practice for OAuth 2.0 Security). Mutual TLS und DPoP sind zwei unterschiedliche Verfahren zur Senderbindung; beide ändern Schlüsselbetrieb und Fehlerdiagnose und sind keine blossen Schalter am Gateway (RFC 8705 – OAuth 2.0 Mutual-TLS Client Authentication, RFC 9449 – OAuth 2.0 Demonstrating Proof of Possession).

Retries, Pagination und Events erzeugen mehrere technische Vorgänge für eine fachliche Aktion. Korrelation und Audit müssen sie wieder zu einem nachvollziehbaren Ablauf verbinden.

Observability und beweisbare Aufrufe

Metriken zeigen das Volumen, Logs einzelne Entscheidungen und Traces den Weg eines Requests über Prozessgrenzen. OpenTelemetry modelliert einen Trace als kausale Menge von Spans und definiert Trace- und Span-IDs für die Korrelation (OpenTelemetry – Traces). Für Adminzwecke sollte ein API-Aufruf mindestens folgende Fakten rekonstruierbar machen:

IDs werden an Prozessgrenzen weitergereicht, aber nicht blind von beliebigen externen Clients als interne Autorität übernommen. Metriklabels vermeiden Benutzer-IDs, vollständige Pfade und andere hochkardinale Werte. Payloads, Authorization-Header, Cookies und Webhook-Signaturen gehören standardmässig nicht in Telemetrie. Ein Trace kann den Pfad belegen, ersetzt aber keinen manipulationsgeschützten Auditnachweis über eine privilegierte Änderung.

Versionierung, Deprecation und Sunset

Eine Versionsnummer ist kein Lifecycle. Zunächst wird zwischen kompatiblen Erweiterungen und Breaking Changes unterschieden. Neue optionale Felder, zusätzliche Enumwerte oder eine veränderte Reihenfolge können Clients trotz vermeintlicher Abwärtskompatibilität brechen, wenn diese den Vertrag zu eng implementieren. Consumer-Tests und Schema-Diffing prüfen deshalb nicht nur Pfade, sondern Semantik, Berechtigungen, Fehler und Grenzwerte.

Versionen können im Pfad, Host, Header oder Medientyp stehen; entscheidend ist, dass Routing, Dokumentation, Telemetrie und Support dieselbe Variante eindeutig benennen. Für die Ausphasung standardisiert RFC 9745 das HTTP-Feld Deprecation; RFC 8594 definiert Sunset als Zeitpunkt, ab dem eine Ressource voraussichtlich nicht mehr antwortet. Beide ersetzen keine Migrationsanleitung, keinen alternativen Link und keinen nachgewiesenen Clientbestand (RFC 9745 – The Deprecation HTTP Response Header Field, RFC 8594 – The Sunset HTTP Header Field).

Ein belastbarer Abkündigungsprozess umfasst Inventar der Consumer, Nutzungsmetriken pro Version und Client, angekündigte Termine, Parallelbetrieb, Testumgebung, Rückfallweg und eine explizite Abschaltentscheidung. «Im Wiki angekündigt» ist kein Nachweis, dass unbeaufsichtigte Automationen migriert wurden.

Betriebsmodelle: lokal, Cloud und Control Plane

Der Ort einer API entscheidet nicht allein über Sicherheit oder Beherrschbarkeit. Eine lokale Schnittstelle kann direkt an privilegierte Betriebssystemkonten, langlebige Schlüssel und wenig segmentierte Netze gebunden sein. Eine Cloud-Control-Plane kann dagegen starke Workload-Identitäten und Auditlogs bieten, bleibt aber von Internetpfad, Provider-IAM, Tenantkonfiguration, Quotas und Serviceverfügbarkeit abhängig. Entscheidend ist der konkrete Fehler- und Vertrauensraum.

Backups sichern nicht automatisch eine externe API. Für Wiederanlauf werden vielmehr Verträge, Clientkonfiguration, Secret-Referenzen, Zertifikate, Gatewayregeln, Idempotenzzustand, offene Jobs und die Fähigkeit zur Reconciliation inventarisiert. Recoverytests müssen auch abgelaufene Tokens, geänderte DNS-Ziele und zurückgesetzte Continuation Tokens abdecken.

Technische Geschichte

Frühe verteilte Schnittstellen waren häufig eng an Remote Procedure Call und sprachspezifische Stubs gebunden. SOAP 1.2 definierte später einen XML-basierten Nachrichtenrahmen mit extensiblem Verarbeitungsmodell und wurde zusammen mit WSDL und WS-* in Unternehmensplattformen verbreitet (W3C – SOAP Version 1.2 Part 1). Roy Fieldings Dissertation beschrieb 2000 REST als Architekturstil für verteilte Hypermedia-Systeme und leitete die Constraints aus Anforderungen an das Web ab – nicht als Rezept «HTTP plus JSON» (Fielding – Architectural Styles and the Design of Network-based Software Architectures).

HTTP entwickelte sich parallel von persistenten TCP-Verbindungen in HTTP/1.1 über multiplexte Streams in HTTP/2 bis zu HTTP/3 über QUIC. Die Methodik und Statussemantik sind in RFC 9110 transportübergreifend beschrieben; die Wireformate liegen in RFC 9112, RFC 9113 und RFC 9114 (RFC 9112 – HTTP/1.1, RFC 9113 – HTTP/2, RFC 9114 – HTTP/3).

JSON wurde als leichtgewichtiges Austauschformat standardisiert; JSON Schema und OpenAPI ergänzten maschinenlesbare Struktur- und Operationsverträge. GraphQL beschreibt ein typisiertes Query- und Ausführungsmodell, bei dem Clients Felder auswählen; gRPC verbindet serviceorientierte RPC-Definitionen mit Protocol Buffers und HTTP/2-basiertem Framing (JSON Schema Specification, OpenAPI Specification, GraphQL Specification, gRPC – What is gRPC?, Protocol Buffers – Language Guide). Event- und Streamingmodelle ergänzen Request/Response, beseitigen aber weder Verträge noch Zustell- und Konsistenzfragen.

Admin-Checkliste auf einen Blick

Nach Vertrag, Laufzeit und Betrieb verdichtet die folgende Checkliste die Fragen, die vor Freigabe einer API beantwortet sein sollten. Sie ist als Abnahmehilfe gedacht, nicht als Ersatz für die vorangehenden Erklärungen.