Geschätzte Lesezeit : 7 min · Veröffentlicht
Wählen Sie Aufgaben vor Adressen
Listenverwendungen wie das Auffinden eines Produkts, das Lesen der Verfügbarkeit, das Aktualisieren eines Datensatzes oder die Verfolgung der Verarbeitung. Definieren Sie autorisierte Personen und Systeme für jeden Vorgang. Eine öffentliche Lese-API und eine administrative API haben unterschiedliche Zugriffsanforderungen.
Bereiten Sie ein Anfrage- und Antwortbeispiel für jede wesentliche Aufgabe mithilfe von synthetischen Werten und erklärten Feldern vor. Unterscheiden Sie stabile Kennungen, Etiketten, Einheiten und Daten. Definieren Sie fehlende Daten, anstatt plausible Werte für unbekannte Informationen zu ersetzen.
Große Kennungen im JSON-Vertrag ausdrücklich darstellen. Mit JavaScript Number und binary64 liegen Ganzzahlen von −9007199254740991 bis 9007199254740991 im exakten Interoperabilitätsbereich der RFC 8259. 9007199254740992 ist darstellbar, aber keine sichere Ganzzahl: Der benachbarte Token 9007199254740993 wird beim üblichen JavaScript-JSON-Decodieren zu 9007199254740992 gerundet.
Als JSON-Zeichenkette behält die Kennung ihre Ziffern. Darstellung zwischen Erzeuger, Schema und Verbraucher vereinbaren; ein schon gerundetes Number wird durch Textumwandlung nicht wieder exakt. Andere Bibliotheken können mehr Präzision behalten: unterstützte Clients testen. Gültiges JSON garantiert keine Werttreue und Kennungstypen dürfen nicht unbemerkt wechseln.
Scrollen Sie die Tabelle horizontal, um alle Spalten zu lesen. Mit der Tastatur fokussieren Sie den Tabellenbereich und verwenden die Pfeiltasten.
| JSON-Beispieltoken | Angezeigter JavaScript-Wert | Bedeutung |
|---|---|---|
| 9007199254740991 | 9007199254740991 | Sichere Ganzzahl im Beispiel |
| 9007199254740992 | 9007199254740992 | Exakt, aber außerhalb des sicheren Bereichs |
| 9007199254740993 | 9007199254740992 | Gerundet: ursprüngliche letzte Ziffer verloren |
| "9007199254740993" | "9007199254740993" | Exakte Zeichenkette; vereinbarter Texttyp |
einen expliziten Vertrag beschreiben
OpenAPI bietet ein sprachunabhängiges Beschreibungsformat für HTTP-APIs, das Operationen, Parameter, Antworten und Modelle abdeckt. Wählen Sie eine Version aus, die von Ihren Tools unterstützt wird, und bewahren Sie das Dokument mit dem Projekt auf. Die neueste Version passt nicht automatisch zu jeder Toolchain.
Beschränkungen der Dokumentnutzung, Paginierung, Filter, Bestellung, Fehler und leere Antworten. Behandeln Sie Cors nicht als Nachweis der Zulassung. Überprüfen Sie den Betrieb und die Zugriffskontrollen auf Objektebene mit dem technischen Team.
Beschreiben Sie für eine fiktive API zur Anfragenbearbeitung die vier folgenden Antworten getrennt. In diesem Vertrag liefert 201 eine angelegte Ressource mit Location-Header; 202 liefert eine Vorgangsreferenz, weil die Bearbeitung noch nicht abgeschlossen ist. Machen Sie nicht aus jeder 2xx-Antwort „Vorgang abgeschlossen“. Der Client muss Status, Header und das für die Operation beschriebene Modell auswerten.
Eine 204-Antwort enthält keinen als JSON zu dekodierenden Inhalt. Im Beispiel erhält eine syntaktisch korrekte Anweisung, die gegen eine Fachregel verstößt, 422 mit strukturiertem Problem in application/problem+json. Wird das Element status geliefert, muss sein Erzeuger es mit dem tatsächlichen HTTP-Status abgleichen; übersetzter Text in detail darf kein Entscheidungsschlüssel der Software sein. Dokumentieren Sie stabile Problemkennungen und die erwartete Korrektur.
Scrollen Sie die Tabelle horizontal, um alle Spalten zu lesen. Mit der Tastatur fokussieren Sie den Tabellenbereich und verwenden die Pfeiltasten.
| Geplante Antwort | Belegter Sachverhalt | Prüfung beim Verbraucher |
|---|---|---|
| 201 Created | Ressource angelegt | Vertraglich vorgesehenes Location und erzeugte Kennung prüfen |
| 202 Accepted | Bearbeitung angenommen, nicht abgeschlossen | Vorgangsreferenz behalten; endgültiges Ergebnis abwarten |
| 204 No Content | Aktion erfolgreich, ohne Antwortinhalt | Keinen leeren Inhalt als JSON dekodieren |
| 422 Unprocessable Content | Anweisung verstanden, nach Fachregel nicht verarbeitbar | Strukturiertes Problem lesen und passende Korrektur anbieten |
- RFC 9110 : HTTP Semantics
RFC 9110, abgerufen am 22. Oktober 2026: Statussemantik. Antworten und Pflichtfelder definieren hier einen fiktiven Vertrag.
- RFC 9457 : Problem Details
RFC 9457, abgerufen am 22. Oktober 2026: Problemformat und Rolle des Elements status.
Verhindern, dass eine Änderung die eines anderen Bearbeiters überschreibt
- Zwei Lesezugriffe auf r7
- Erstes Schreiben: r8
- Veraltetes Schreiben: 412
- Vor Wiederaufnahme vergleichen
Fiktiver Fall: Zwei Bearbeiter öffnen DEMO-17 mit dem starken ETag "r7". Der erste speichert eine Korrektur; die aktuelle Darstellung wird zu "r8". Der zweite arbeitet noch mit "r7". Bedingtes Schreiben kann diesen Unterschied vor dem Ersetzen der veröffentlichten Version erkennen.
Unterstützt die API diesen Vertrag, sendet der Client If-Match mit dem erhaltenen starken Validator. Der Server vergleicht die Version vor dem Schreiben; im Beispiel folgt bei einer Änderung 412. W/"r7" ist schwach und erfüllt den starken Vergleich nicht. If-Match: * prüft, ob eine aktuelle Darstellung existiert, nicht ob sie seit dem Lesen unverändert blieb.
Den Entwurf des zweiten Bearbeiters erhalten, die aktuelle Version lesen und Unterschiede vor einer neuen Entscheidung anzeigen. Den Validator automatisch durch "r8" zu ersetzen und den alten Entwurf erneut zu senden, würde den Schutz umgehen. Prüfung und Schreiben müssen im Speicher unteilbar sein; zwei gleichzeitige Anfragen mit demselben Validator dürfen nicht beide dieselbe Version überschreiben.
Die Nebenläufigkeitskontrolle ersetzt weder Authentifizierung noch Objektberechtigungen oder Feldvalidierung. Sie garantiert auch keine einmalige Ausführung eines externen Aufrufs. Diese Eigenschaften getrennt prüfen und fehlende Vorbedingungen dokumentieren; 428 kann eine bedingte Anfrage verlangen.
Scrollen Sie die Tabelle horizontal, um alle Spalten zu lesen. Mit der Tastatur fokussieren Sie den Tabellenbereich und verwenden die Pfeiltasten.
| Schritt | Version und Anfrage | Erwartetes Ergebnis dieses Vertrags |
|---|---|---|
| Beide lesen | ETag: "r7" | Beide behalten den Validator mit ihrem Entwurf. |
| Erstes Speichern | If-Match: "r7" → Version "r8" | Die erste Korrektur bleibt erhalten. |
| Veraltetes zweites Speichern | If-Match: "r7"; aktuell "r8" | 412; gespeicherte Korrektur nicht ersetzen. |
| Bewusster Abgleich | "r8" lesen, vergleichen, entscheiden | Entwurf erhalten und Rechte vor erneutem Schreiben prüfen. |
- IETF · RFC 9110 § 13.1.1
IETF : Bedingte Schreibzugriffe und Vorbedingungen
- IETF · RFC 6585 § 3
428 · Precondition Required
Grenzen und Berechtigungen testen
Versuchen Sie es mit einem vorhandenen Objekt, einem fehlenden Objekt, einem ungültigen Parameter und einer Liste, die länger als eine Seite ist. Überprüfen Sie die nächste Seite auf Verluste oder Wiederholungen innerhalb des gewählten Aktualisierungsmodells. Zustandsbeschränkungen, die die API nicht garantieren kann.
Verwenden Sie Testkonten mit unterschiedlichen Berechtigungen. Der Versuch liest und ändert sich außerhalb des zulässigen Umfangs mithilfe von synthetischen Daten. Zeichnen Sie erwartete Status und nützliche Nachrichten auf, ohne interne Traces oder Konfigurationsgeheimnisse freizulegen.
Planänderung und Unterstützung
Unterscheiden Sie ein hinzugefügtes Feld von einem entfernten Feld oder einer geänderten Bedeutung. Identifizieren Sie Verbraucher vor einer inkompatiblen Änderung. Erläutern Sie die Übergangszeit und wie Sie Integrationen erkennen können, die noch den früheren Vertrag verwenden.
Liefern Sie ein ausführbares Beispiel für eine Testumgebung, eine Testmatrix und einen technischen Kontakt. Beziehen Sie beobachtete Fehler nach der Freigabe auf dokumentierte Beispiele. Die auf den Idealfall beschränkte Dokumentation lässt Integratoren ohne Anleitung für Ablehnungen und Unterbrechungen.
Primärdokumentation: OpenAPI-Initiative – Spezifikation.
Referenzdokumente
- OpenAPI-Initiative – Spezifikation · Quelle eingesehen
- IETF : RFC 8259: JSON numbers · Quelle eingesehen
- TC39 : Number.isSafeInteger · Quelle eingesehen
Inhalt aktualisiert
Dokumentierte Grundlagen zu diesem Thema
| Referenz | Wert oder Syntax | Geltungsbereich |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | Standard-JSON erlaubt weder Kommentare noch abschließende Kommas; Zeichenfolgen nutzen doppelte Anführungszeichen. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | Der explizite Versatz bezieht Ortszeit auf UTC; dieses Beispiel ist kein Termin. |
| HTTP · If-Match | If-Match: "r7" → 412 | If-Match vergleicht vor dem Schreiben einen starken Validator. Im dargestellten Vertrag erhält eine veraltete Version 412; den Entwurf für den Abgleich behalten. |
| HTTP · 428 | 428 · Precondition Required | Mit 428 kann ein Server eine bedingte Anfrage verlangen. Die Verwendung gehört in den Vertrag; der Status stellt selbst keine Sperre bereit. |
Die Daten geben die Prüfung der Quellen an. Diese Hinweise sind weder ein Website-Audit noch eine umfassende Konformitätserklärung.
