REST-API-Qualität in KI-gestützter Entwicklung sichern

💡 Kurzfassung

• Vor dem Coding: Lassen Sie den Agenten Geschäftsprozess, Ressourcenmodell, Zugriffsgrenzen, Fehlerverhalten und Vertragsänderung erklären. Fehlende Informationen darf er nicht durch Annahmen ersetzen.
• Im Review: Prüfen Sie HTTP-Methoden, Wiederholungsverhalten, Datensatz-Eigentümerschaft, Fehlervertrag, zu breite Datenzugriffe und Abwärtskompatibilität unabhängig.
• Vor der Auslieferung: Erzwingen Sie OpenAPI-Validierung, Vertrags- und Breaking-Change-Tests, negative Autorisierungstests und abgestimmte Dokumentation in der Pipeline. Geschäftsentscheidungen bleiben menschliche Verantwortung.

2021 veröffentlichte ich auf dieser Website eine sieben Teile umfassende REST-Reihe: REST-Komponenten, Design-Details, URI-Struktur, Fehlerbehandlung, Authentifizierung, Sicherheit und Dokumentation. Sechs dieser Artikel hatten auch englische Ausgaben.

Die meisten Grundsätze gelten weiterhin. Ich ziehe die Reihe nicht zurück, weil sie falsch geworden wäre. Sie entstand für eine Arbeitsweise, bei der Entwickler jedes Thema nacheinander studierten, die REST-Entscheidungen lernten und anschließend den Code schrieben.

Heute beschreiben viele Entwickler einem KI-Coding-Agenten in wenigen Sätzen, was sie brauchen, und arbeiten mit dem resultierenden Code weiter. Die alten Artikel getrennt zu lassen, würde solide Regeln in einem weniger üblichen Lernpfad einschließen. Deshalb ersetze ich sie durch diesen Artikel: die Grundsätze dort einsetzen, wo sie in KI-gestützter API-Arbeit entscheidend sind – im ersten Prompt, im Code Review und in Auslieferungsprüfungen.

Warum ist ein REST-API-Prompt unvollständig?

Bitten Sie einen Agenten, „eine CRUD-API für Kundendaten“ zu schreiben, können Sie in Minuten funktionierende Endpunkte erhalten. Funktionierender Code beantwortet jedoch nicht:

• Darf ein Kundendatensatz physisch gelöscht, archiviert oder anonymisiert werden?
• Was geschieht, wenn dieselbe Löschanfrage zweimal eintrifft?
• Unter welchen Bedingungen darf ein Nutzer den Kundendatensatz eines anderen sehen?
• Wen betrifft es, wenn sich eine vom mobilen Client verwendete Antwort ändert?
• Kann ein Client nach einem Fehler sicher erneut versuchen?

Der erste Schritt zu REST-Qualität besteht darin, diese Entscheidungen zu treffen. URIs und Anwendungscode kommen danach. Ein Agent füllt ausgelassene Entscheidungen oft mit plausibel wirkenden Annahmen. Eine technische Präferenz wird dann unbemerkt zu einer Geschäftsentscheidung über Aufbewahrung, Zugriff oder Integration.

Eine Anweisung vor dem ersten Code

Do not write code yet. First, for this API change:

1. Explain the business process, the resource owner, and the expected outcome.
2. List the resources, their relationships, and the URI structure you propose.
3. For every endpoint, state the HTTP method, its side effects, and what happens
   if the same request is repeated.
4. Define successful responses, error conditions, and what the client should do
   for each error.
5. Show authentication, authorization, role, tenant, and record-ownership checks
   separately.
6. List input validation, returned fields, request size, rate limits, logging,
   and sensitive-data risks.
7. Show the proposed difference from the current OpenAPI contract and any
   backward-compatibility risk.
8. If you propose a new database, cache, queue, or service, explain the concrete
   need it addresses and its operating cost.

If information is missing, do not make assumptions. List the questions and wait.

Diese Anweisung lehrt den Agenten nicht REST. Sie macht sichtbar, welche Entscheidungen vor dem Code getroffen werden müssen. Zugleich verhindert sie, dass eine Lösch- oder Aufbewahrungsentscheidung, die dem Product Owner gehört, als technische Annahme umgesetzt wird.

Frühere REST-Grundsätze mit KI bewahren

Ein enger HATEOAS-Grundsatz bleibt ebenfalls relevant: Ist die nächste gültige Aktion Teil des Geschäftsworkflows, darf die Antwort den Client nicht zum Raten zwingen. Links oder Aktionsmöglichkeiten müssen in KI-gestützter API-Arbeit eine explizite Vertragsentscheidung sein, nicht improvisiertes JSON.

Diese Tabelle kann als API-Entwicklungsregel dienen. Regeln für jede API-Arbeit gehören in dauerhafte Agent-Anweisungen des Repositories. Produkt- oder endpunktspezifische Entscheidungen gehören ins Arbeitsbriefing und in den OpenAPI-Vertrag.

Anweisung für einen zweiten Agenten im Review

Den Agenten, der den Code schrieb, um Selbstprüfung zu bitten, kann helfen. Ein Agent im selben Kontext erkennt seine eigene Annahme aber möglicherweise nicht als Fehler. Review ist eine stärkere Kontrolle, wenn es eine getrennte Aufgabe und nach Möglichkeit ein eigener Agentenkontext ist.

Review this API change as an independent reviewer. Do not change code yet.
Do not treat the implementing agent’s explanation as evidence; use the existing
OpenAPI contract, repository rules, and tests instead.

Check the following:
- Are the resource model and URIs consistent with the existing API?
- Are HTTP methods, side effects, and retry behaviour correct?
- Do success and error responses match the contract?
- Are authentication, functional authorization, tenant, and record-ownership
  checks implemented separately?
- Are inputs, writable fields, and returned data broader than necessary?
- Is there a contract change that could break existing clients?
- Alongside the successful flow, are there tests for negative authorization,
  validation, rate limits, and retries?

For every finding, state the affected endpoint, evidence, risk, and required test.
Do not make corrections until the review is approved.

Ziel ist nicht, Code-Stil zu korrigieren. Das Review soll finden, wo der Agent eine Geschäftsentscheidung missverstanden, REST-Verhalten gebrochen oder eine Sicherheitsgrenze übersprungen hat.

Welche Fehler soll die Pipeline automatisch stoppen?

Prompt und Review allein reichen nicht. Gelangen wiederholbare Regeln nicht in die Pipeline, kann derselbe Fehler in der nächsten Änderung erneut auftreten. Mindestens diese vier Prüfungen sollten automatisiert sein:

1. Ist der OpenAPI-Vertrag gültig und mit der Anwendung abgestimmt?
2. Führt der Vertrags-Diff eine nicht abwärtskompatible Änderung ein?
3. Bestehen Vertrags-, negative Autorisierungs-, Validierungs- und Wiederholungstests?
4. Hat die veröffentlichte Dokumentation dieselbe Version wie der Vertrag?

Änderungen am Zugriffsmodell, Zahlungsverhalten, sensiblen Daten, der Datenlöschrichtlinie oder bestehenden Clients sollten zudem zur Freigabe durch eine benannte Person anhalten. Ein weiterer Agent, der „sieht gut aus“ sagt, übernimmt diese Entscheidungen nicht.

Warum die alte Reihe in einen Artikel überführen?

Die alte Reihe sollte Entwicklern REST beibringen. Der aktuelle Bedarf besteht darin, dieses Wissen im KI-gestützten Entwicklungsfluss nicht verschwinden zu lassen.

Eine Kontrollsequenz ist darum nützlicher als sieben getrennte Artikel:

1. Geschäftsentscheidung treffen.
2. Den Agenten die fehlenden Entscheidungen offenlegen lassen.
3. Den Vertrag vor dem Code sehen.
4. Die Implementierung durch ein unabhängiges Review schicken.
5. Wiederholbare Regeln in der Pipeline verpflichtend machen.

Kann ein Team diese Kontrollen nicht in Prompts, Repository-Anweisungen und Pipeline sichtbar machen, hat es sein früheres REST-Wissen nicht in die neue Arbeitsweise übertragen. Ein Agent kann schnell Code schreiben. Menschen entscheiden weiterhin, was die API verspricht und welche Risiken sie nicht akzeptieren können.

Quellen

• OpenAPI Specification
• RFC 9110: HTTP Semantics
• RFC 9457: Problem Details for HTTP APIs
• OWASP API Security Top 10, 2023