Suchen
Geben Sie mindestens zwei Zeichen ohne persönliche Daten ein.

    BibliothekArtikel und FAQs Ihr ProjektFordern Sie ein Angebot an
    SpracheDE ▾
    Praktische Anleitungen

    Dokumentieren und testen Sie eine API aus ihren Anwendungsfällen

    Mit einer nützlichen API kann ein anderes Team verstehen, was es anfordern kann und was es erhält. Der Vertrag sollte testbar, versioniert und mit dem Betriebsdienst übereinstimmen.

    Siehe die Methode

    Illustration — Dokumentieren und testen Sie eine API aus ihren Anwendungsfällen
    KI-generierte Illustration

    Wählen Sie Aufgaben vor Adressen

    JavaScript: numerisches 9007199254740993 wird gerundet; als Zeichenkette bleiben Ziffern erhalten.
    Illustration · JSON.parse-Beispiel: Number rundet, String erhält die Ziffern. Textdarstellung vor Umwandlung vereinbaren.

    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.

    JavaScript-JSON-Decodierung: Präzision und Typ
    JSON-BeispieltokenAngezeigter JavaScript-WertBedeutung
    90071992547409919007199254740991Sichere Ganzzahl im Beispiel
    90071992547409929007199254740992Exakt, aber außerhalb des sicheren Bereichs
    90071992547409939007199254740992Gerundet: 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.

    Vier Antworten einer fiktiven API und ihre Folgen im Client
    Geplante AntwortBelegter SachverhaltPrüfung beim Verbraucher
    201 CreatedRessource angelegtVertraglich vorgesehenes Location und erzeugte Kennung prüfen
    202 AcceptedBearbeitung angenommen, nicht abgeschlossenVorgangsreferenz behalten; endgültiges Ergebnis abwarten
    204 No ContentAktion erfolgreich, ohne AntwortinhaltKeinen leeren Inhalt als JSON dekodieren
    422 Unprocessable ContentAnweisung verstanden, nach Fachregel nicht verarbeitbarStrukturiertes 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

    1. Zwei Lesezugriffe auf r7
    2. Erstes Schreiben: r8
    3. Veraltetes Schreiben: 412
    4. 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.

    Zwei Bearbeiter, eine aktuelle Version: fiktiver Testablauf
    SchrittVersion und AnfrageErwartetes Ergebnis dieses Vertrags
    Beide lesenETag: "r7"Beide behalten den Validator mit ihrem Entwurf.
    Erstes SpeichernIf-Match: "r7" → Version "r8"Die erste Korrektur bleibt erhalten.
    Veraltetes zweites SpeichernIf-Match: "r7"; aktuell "r8"412; gespeicherte Korrektur nicht ersetzen.
    Bewusster Abgleich"r8" lesen, vergleichen, entscheidenEntwurf erhalten und Rechte vor erneutem Schreiben prüfen.

    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

    Inhalt aktualisiert

    Dokumentierte Grundlagen zu diesem Thema

    Dokumentierte Grundlagen zu diesem Thema
    ReferenzWert oder SyntaxGeltungsbereich
    RFC 8259 · JSON
    application/json · UTF-8Standard-JSON erlaubt weder Kommentare noch abschließende Kommas; Zeichenfolgen nutzen doppelte Anführungszeichen.
    RFC 3339 · Date-time
    2026-10-22T09:00:00+02:00Der explizite Versatz bezieht Ortszeit auf UTC; dieses Beispiel ist kein Termin.
    HTTP · If-Match
    If-Match: "r7" → 412If-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 RequiredMit 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.

    HTTP-Status, JSON und Fachergebnis trennen

    Wählen Sie einen fiktiven Austausch und testen Sie dessen lokales Einlesen. HTTP-Erfolg, lesbares JSON und abgeschlossene Operation sind getrennt zu prüfen.

    Die Auszüge sind unvollständig und verwenden Demoadressen. Der Versuch erzeugt eine Response im Speicher: kein Serverkontakt, keine Simulation von Netzwerk, Cache oder Fachverarbeitung.

    200Eine neue vollständige Darstellung
    Bedeutung
    Hier beantwortet der Server ein bedingtes GET mit JSON-Inhalt und dem Validator demo-v2.
    Was zu prüfen ist
    Vergleichen Sie If-None-Match, ETag und Inhaltsrevision. Der lokale Versuch liest das JSON dieses Beispiels.
    Worauf zu achten ist
    Status 200 garantiert weder gültiges JSON noch richtige Fachdaten. Erfolgreiches Einlesen hier bestätigt nicht das Schema Ihrer eigenen Daten.
    Fiktiver Austausch als Auszug
    GET /demo/catalogue
    If-None-Match: "demo-v1"
    
    HTTP/1.1 200 OK
    ETag: "demo-v2"
    Content-Type: application/json
    
    {"revision":"demo-v2"}

    202Angenommen, Verarbeitung noch offen
    Bedeutung
    202 meldet die Annahme zur Verarbeitung, nicht deren Abschluss. Der fiktive Inhalt nennt queued.
    Was zu prüfen ist
    Bewahren Sie DEMO-42 auf und verfolgen Sie den Zustand gemäß API-Vertrag, Zugriffsrechten und Wiederholungsgrenzen.
    Worauf zu achten ist
    Response.ok ist true. Weder dieser Wert noch lesbares JSON belegt den Abschluss. Felder und Überwachungsadresse sind fiktive Konventionen.
    Fiktiver Austausch als Auszug
    POST /demo/jobs
    
    HTTP/1.1 202 Accepted
    Location: /demo/jobs/DEMO-42
    Content-Type: application/json
    
    {"job":"DEMO-42","status":"queued"}

    204Anfrage erfüllt, kein Antwortinhalt
    Bedeutung
    204 zeigt eine erfüllte Anfrage ohne Antwortinhalt an. Der Auszug überträgt kein JSON.
    Was zu prüfen ist
    Behandeln Sie den fehlenden Inhalt gemäß Vertrag. Klären Sie vor einer Ergebnismeldung genau, was der Endpunkt bestätigt.
    Worauf zu achten ist
    JSON-Einlesen scheitert beim leeren Inhalt trotz Response.ok gleich true. Bei Webhooks kann nur der Empfang bestätigt sein; spätere Fachaktionen sind gesondert abzugleichen.
    Fiktiver Austausch als Auszug
    POST /demo/events
    
    HTTP/1.1 204 No Content

    304Kopie erneut validiert, kein neuer Inhalt
    Bedeutung
    304 beantwortet eine bedingte Anfrage: Die gespeicherte Darstellung kann wiederverwendet werden. Es kommt kein neuer Inhalt.
    Was zu prüfen ist
    Vergleichen Sie den gesendeten Validator mit der vorhandenen Kopie demo-v2. Die Deutung hängt auch von dieser Kopie ab.
    Worauf zu achten ist
    Der Versuch erzeugt eine einzelne Response 304, keinen HTTP-Cache. Bei echtem fetch kann der Browser die gespeicherte Antwort liefern; Netzwerkstatus und Skriptstatus können abweichen.
    Fiktiver Austausch als Auszug
    GET /demo/catalogue
    If-None-Match: "demo-v2"
    
    HTTP/1.1 304 Not Modified
    ETag: "demo-v2"

    Technische Quellen : RFC 9110 §15 · MDN · Response.ok · MDN · Response.json() · WHATWG · Fetch · .

    Funktionale Validierungsmatrix zur Projektanpassung

    Diese vorgeschlagenen Kontrollen verwenden fiktive Fälle. Entscheiden Sie, welches Verhalten mit dem Team zu erwarten ist, schreiben Sie das Ergebnis auf und weisen Sie vor der Veröffentlichung ungelöste Abweichungen zu.

    Scrollen Sie die Tabelle horizontal, um alle Spalten zu lesen. Mit der Tastatur fokussieren Sie den Tabellenbereich und verwenden die Pfeiltasten.

    Testfälle, erwartete Ergebnisse und nützliche Beweise
    FallErwartetes ErgebnisBeweis zu behalten
    vorhandene und fehlende RessourcenJedes Ergebnis stimmt mit dem dokumentierten Status- und Antwortmodell überein.Anfrage, Antwort und entsprechendes Vertragsbeispiel aus der Testumgebung erfasst.
    Parameter außerhalb des BereichsDie Ablehnung ist verständlich und stellt keine interne Stack-Trace offen.Öffentliche Nachricht und Ergebnis in der Akzeptanzmatrix beibehalten.
    Zwei BerechtigungsstufenEine verbotene Ressource bleibt auch mit einer bekannten Kennung unzugänglich.Vergleichen Sie die Ergebnisse mit zwei synthetischen Konten mit explizit unterschiedlichen Berechtigungen.
    Paginierung und FilterwechselToken-Handling und Reise-Neustart-Verhalten werden definiert.Bestellung, zurückgegebene Kennungen und Regeln, die beim Ändern des Filters angewendet werden.

    Häufig gestellte Fragen

    Reicht die generierte Dokumentation aus, um eine API zu testen?

    Es hilft beim Lesen eines Vertrages, aber Berechtigungen, fehlende Daten, Fehler, Listen und Änderungen müssen weiterhin getestet werden. Vergleichen Sie Beispiele mit den tatsächlichen Antworten der Testumgebung.

    Ersetzt CORS die Zugriffsberechtigungen?

    Nein. Die originellen Regeln ersetzen nicht die Operations- und Objektberechtigungen des Dienstes. Beschreiben Sie diese Berechtigungen und testen Sie die serverseitige Durchsetzung mit Testkonten.