Wie das hier geprüft wird
Dokumentation ist eine Sammlung von Zusagen: Dieser Endpunkt existiert, er antwortet in dieser Form, dieses Snippet läuft, dieser Tarif darf ihn aufrufen. Nichts an einer Dokumentationsseite macht davon irgendetwas wahr. Diese Seite handelt von der Maschinerie, die genau das tut, und davon, wie Sie es prüfen können, ohne uns irgendetwas glauben zu müssen.
Warum es diese Seite gibt
Leser können nicht unterscheiden zwischen Dokumentation, die aus einem laufenden System erzeugt wurde, und Dokumentation, die ein Modell über ein System geschrieben hat, das es nie aufgerufen hat. Beides liest sich flüssig. Beides wirkt vollständig. Eines davon schickt Sie zu einem Endpunkt, den es nie gab, mit einer Beispiel-ID, die nie im Katalog stand, unter einem Tarif, der ihn nicht erreichen kann.
colt-1911beretta-m9mp5Wir wissen das, weil alle drei Fälle hier vorgekommen sind. Die Referenz beschrieb einmal zwei SDK-Methoden, die es nicht gab, und nannte zwei Fehlerstatus, wo die Operation sechs deklariert. Veröffentlichte Beispiele nannten `colt-1911`, `beretta-m9` und `mp5`. Keinen davon hat dieser Katalog je geführt. Die erste Handlung eines Lesers ist, ein Beispiel einzufügen, und eines, das einen fehlenden Datensatz nennt, lehrt ihn, die API sei kaputt. Jeder Mechanismus unten entstand nach genau so einem Fehler, und jeder macht seine Fehlerklasse unmöglich statt unwahrscheinlich.
Was geprüft wird und was jede Prüfung verhindert
Acht Mechanismen, jeder gegen eine andere Art, wie Dokumentation falsch wird. Sie laufen in der CI, bei jedem Push und nach Zeitplan jede Nacht.
- 01
Die Referenz wird erzeugt, nicht geschrieben
Jede Endpunktseite, Feldtabelle, jeder Statuscode und jede Zugriffsregel der API-Referenz wird aus der OpenAPI-Spezifikation abgeleitet, die diese API ausliefert. Es gibt nirgends eine handgepflegte Endpunktliste, also ist eine Route, die ohne Dokumentation geändert wird, schlicht nicht möglich: Die Seite ist eine Sicht auf den Vertrag.
Ohne das: ein dokumentierter Endpunkt, der 404 antwortet, oder eine Feldtabelle, die eine Payload beschreibt, die die API nicht mehr sendet.
- 02
Die SDK-Referenz wird aus dem SDK erzeugt
Signaturen, Argumente, Rückgabetypen und der Endpunkt, den jede Methode aufruft, werden aus den veröffentlichten Paketen gelesen und mit der Spezifikation verknüpft. Eine Methode, deren Endpunkt nicht auflösbar ist, lässt den Build scheitern: Ein neuer SDK-Aufruf ist dokumentiert, oder die CI hält an.
Ohne das: eine Client-Bibliothek und ihre Dokumentation, die zwei verschiedene Oberflächen beschreiben. So werden Methoden dokumentiert, die es nicht gibt.
- 03
Jede ID in jedem Beispiel ist echt
Die Waffen-Slugs, Patronen-IDs, Kategorien und Vokabularwerte in den Beispielen werden gegen die Katalogdaten geprüft, aus denen die Produktion befüllt wird. Ein Beispiel, das einen Datensatz nennt, den wir nicht haben, lässt den Build scheitern. Auch die Aussagekraft wird geprüft: Ein Beispiel für "Varianten auflisten" muss einen Datensatz nennen, der tatsächlich Varianten hat.
Ohne das: ein erster Aufruf, der 404 oder ein leeres Array liefert. Das liest sich wie eine kaputte API, nicht wie eine veraltete Seite.
- 04
Jedes abgedruckte Beispiel wird ausgeführt
Jedes Beispiel dieser Referenz läuft in der Umgebung, in die ein Leser es einfügen würde - das cURL von curl, der TypeScript-Tab von node, der Python-Tab von einer virtuellen Umgebung - genau so, wie es abgedruckt ist, nur mit eingesetztem Schlüssel. Die SDK-Beispiele werden aus der Registry in ein frisches Projekt installiert und ebenso ausgeführt. Nächtlich und nach jedem Release.
Ohne das: ein Snippet, das einmal kompilierte, für immer veröffentlicht wurde und an dem Tag aufhörte zu funktionieren, an dem sich ein Argument änderte.
- 05
Auch jedes nicht ausführbare Beispiel wird geprüft
Die Unity-, Unreal- und GDScript-Tabs sind Fragmente, die in eine Klasse, einen Actor oder eine Szene gehören; eines auszuführen hieße, es in Code zu hüllen, den diese Seite nie abgedruckt hat - und ein Siegel über einer selbst geschriebenen Hülle wäre weniger wert als keines. Stattdessen wird jedes gegen den Endpunkt geprüft, unter dem es steht: es muss diesen Pfad aufrufen und einen Schlüssel mitführen, wo der Endpunkt einen verlangt. Dieses Ergebnis wird neben den ausgeführten veröffentlicht.
Ohne das: ein handgeschriebenes Engine-Beispiel, das auf einen umbenannten Pfad zeigt und dort auf Dauer falsch stehen bleibt, weil es nie jemand aufgerufen hat.
- 06
Jede Operation wird gegen das Dokument geprüft
Eine Suite ruft jede dokumentierte Operation gegen die Produktion auf und prüft Status, Medientyp, Response-Schema, Envelope, zugesagte gegen gesendete Felder und den Cache-Vertrag. Eine Operation, die etwas antwortet, das im Dokument nicht steht, ist ein Fehlschlag, keine Fußnote.
Ohne das: ein Deploy, der still eine Payload geändert hat, während die Referenz weiter die Form vom Vormonat beschreibt.
- 07
Die Tarif-Gates werden in beide Richtungen bewiesen
Jeder gesicherte Endpunkt wird dreifach aufgerufen: ohne Schlüssel, mit einem Schlüssel des in der Referenz genannten Tarifs und mit einem Schlüssel einen Tarif darunter. Die ersten beiden müssen abgewiesen und eingelassen werden; der dritte muss mit `PLAN_REQUIRED` abgewiesen werden.
Ohne das: ein bezahlter Endpunkt, der still einen günstigeren Tarif bedient. Jede andere Prüfung sieht daran vorbei, denn der Body ist gültig und der Status dokumentiert, und niemand meldet, dass er mehr bekommt, als er bezahlt.
- 08
Jede Zahl wird abgeleitet
Katalogzahlen, Endpunktsummen, SDK-Versionen, Limits, Preise und Tarifnamen werden aus den Systemen erzeugt, die sie besitzen: Datenbank, Spezifikation, Paket-Manifeste, Billing-Konfiguration. Texte interpolieren sie; niemand tippt sie ab.
Ohne das: sechs verschiedene Waffenzahlen auf sechs Seiten und eine Preistabelle, die der Rechnung widerspricht.
- 09
Die Daten sagen, woher sie kommen
Datensätze führen die Seiten, aus denen sie zusammengestellt wurden, eine Konfidenzzahl und die Angabe, welche Felder eine Quelle tatsächlich genannt hat. Die Stärke einer Quelle wird aus einer veröffentlichten Liste bestimmt, damit "vier unabhängige Quellen" nicht vier Händler bedeuten kann, die eine Herstellerangabe wiederholen.
Ohne das: eine Spezifikationsdatenbank, die nicht sagen kann, warum sie eine Zahl glaubt, und damit ununterscheidbar von einer, die sie erfunden hat.
Die Belege, vollständig
Jeder Lauf wird so veröffentlicht, wie er war: bestanden, fehlgeschlagen und die Prüfungen, die nicht möglich waren. Eine Seite, die nur grün sein kann, wäre eine Grafik und kein Beleg.
Für Agenten und die Menschen, die sie betreiben
Ein Agent, der eine API-Referenz liest, kann eine geprüfte Seite nicht von einer plausiblen unterscheiden, und er zögert nicht, bevor er aufruft, was er gelesen hat. Damit wird ungeprüfte Dokumentation zum Betriebsrisiko statt zum Qualitätsproblem: Der Fehler landet im Produkt von jemand anderem, zur Laufzeit, in einem Tool-Aufruf, den niemand geprüft hat.
Deshalb sind die Belege maschinenlesbar und ohne Schlüssel abrufbar. Dieselben Läufe, auf die diese Seite verweist, gibt es als JSON, dazu `llms.txt` und Instruktionspakete für die gängigen Coding-Agenten. Ein Agent kann prüfen, ob das Beispiel, das er gleich ausführt, letzte Nacht bestanden hat, und die Person, die ihn betreibt, ebenso.
# Every documented operation, held against this reference, with the plan gatescurl --request GET \ --url 'https://api.gunspec.io/v1/contract' # Whether the printed examples still run: all three reference tabs and both SDKscurl --request GET \ --url 'https://api.gunspec.io/v1/examples/verification'Was das nicht behauptet
Eine Zusage, die zu viel verspricht, ist weniger wert als eine enge, die hält. Vier Dinge, die diese Läufe bewusst nicht beweisen:
- 01
Schreibzugriffe laufen nicht.
Beispiele, die schreiben würden, laufen nicht gegen die Produktion, denn ein nächtlich angelegtes Support-Ticket oder Händlerangebot ist ein echter Datensatz, den jemand aufräumen muss. Sie stehen mit Begründung als "nicht ausgeführt" in der Liste und zählen nie als bestanden.
- 02
Die Game-Engine-Tabs werden nicht ausgeführt.
Die Unity-, Unreal- und GDScript-Beispiele sind Veranschaulichungen, keine Programme: jedes ist ein Fragment, das in eine Klasse, einen Actor oder eine Szene gehört, es gibt also nichts auszuführen, ohne es in Code zu hüllen, den diese Seite nicht abgedruckt hat. Geprüft wird, dass jedes denselben Endpunkt aufruft, den ein ausgeführtes Beispiel abdeckt, und einen Schlüssel mitführt, wo der Endpunkt einen verlangt. Ob die Engine-Anbindung darum herum noch kompiliert, hängt von einem Unity- oder Unreal-Release ab und nicht von dieser API; nichts hier behauptet, das zu beantworten.
- 03
Ein Lauf beweist einen Zeitpunkt.
Ein Lauf beweist, was zum Zeitpunkt des Laufs galt. Jede Seite zeigt, wann das war, damit ein veraltetes Ergebnis auch veraltet aussieht und nicht wie ein aktuelles Bestanden.
- 04
Wie dokumentiert zu antworten heißt nicht, richtig zu sein.
Diese Prüfungen belegen, dass die API sich wie dokumentiert verhält. Ob eine Lauflänge stimmt, ist eine andere Frage, beantwortet von Konfidenz und Herkunft je Datensatz und von einer Genauigkeitsmessung, die noch läuft.
- 05
Das ist unsere eigene CI.
Das ist unsere eigene CI, die über unsere eigene API berichtet. Sie wird vollständig veröffentlicht, samt Fehlschlägen und dem Commit, aus dem sie lief, damit die Aussage prüfbar statt glaubenspflichtig ist. Sie ist jedoch kein externes Audit, und wir nennen sie auch nicht so.
Wenn Sie auf diesen Seiten etwas finden, das nicht stimmt, ist das ein Bug, den wir hören wollen, und der Lauf, der ihn hätte finden müssen, ist ebenfalls einer.