Wie es funktioniert

Architektur

Wohin Ihre Anfrage geht, was über die Antwort entscheidet und woher die Zahlen darin kommen. Sieben Diagramme, jedes mit einem Link auf die Seite mit den Details.

Der Weg einer Anfrage

Jeder Aufruf durchläuft dieselben Prüfungen in derselben Reihenfolge: zuerst der Cache, dann Ihr Schlüssel, dann die Limits Ihres Tarifs - und erst danach wird der Katalog gelesen. Ein 304 oder ein 429 ist eine Antwort, die Sie erhalten, bevor etwas von Ihrem Kontingent für eine Abfrage ausgegeben wurde.

DiagrammEine Anfrage von Ihrem Client bis zur Antwort

100%

flowchart LR
  client["Your client"] --> edge["Our edge"]
  edge -->|"a fresh copy is cached"| cached["Answered from cache"]:::ok
  edge -->|"otherwise"| key["Your API key is checked"]
  key --> limits["Your plan's limits are checked"]
  limits -->|"allowance spent"| capped["Refused: 429 Too Many Requests"]:::fail
  limits -->|"within your plan"| lookup["The catalog is read"]
  lookup --> shape["Shaped to what your plan includes"]
  shape --> answer["Answered: 200, with an ETag to cache against"]:::ok

Eine Anfrage von Ihrem Client bis zur AntwortIhr Client ruft unseren Edge auf, der direkt antwortet, wenn eine frische Kopie dieser Antwort bereits im Cache liegt. Andernfalls wird Ihr API-Schlüssel geprüft, dann die Limits Ihres Tarifs: ein aufgebrauchtes Kontingent ergibt 429 Too Many Requests, eine Anfrage innerhalb Ihres Tarifs liest den Katalog. Was zurückkommt, ist auf die Felder Ihres Tarifs zugeschnitten und trägt einen ETag, gegen den Sie cachen können - die nächste identische Anfrage kann dann mit 304 beantwortet werden.

Wo das beschrieben ist

Limits und Tarife/de/rate-limits Caching und Aktualisierung/de/caching

Was Ihren Statuscode bestimmt

401 betrifft die Zugangsdaten, 403 die Berechtigung - deshalb hilft ein anderer Schlüssel beim einen und nie beim anderen. Jedes Blatt hier ist eine echte Antwort, und jede nennt einen Grund, auf den Ihr Client verzweigen kann.

DiagrammWie eine Anfrage zugelassen oder abgelehnt wird

100%

flowchart TD
  start["A request to /v1"] --> has{"API key sent?"}
  has -->|"no"| open{"Open without a key?"}
  open -->|"yes"| handler["Answered"]:::ok
  open -->|"no"| unauth["Refused: 401 API_KEY_MISSING"]:::fail
  has -->|"yes"| valid{"Key valid and in date?"}
  valid -->|"no"| expired["Refused: 401 KEY_EXPIRED"]:::fail
  valid -->|"yes"| account{"Account in good standing?"}
  account -->|"no"| suspended["Refused: 403 ACCOUNT_SUSPENDED"]:::fail
  account -->|"yes"| plan{"Plan covers this endpoint?"}
  plan -->|"no"| upgrade["Refused: 403 PLAN_REQUIRED"]:::fail
  plan -->|"yes"| handler

Wie eine Anfrage zugelassen oder abgelehnt wirdOhne API-Schlüssel antwortet ein ohne Schlüssel offener Endpunkt normal, jeder andere mit 401 und dem Grund API_KEY_MISSING. Mit Schlüssel ergibt ein ungültiger oder abgelaufener Schlüssel 401 KEY_EXPIRED, ein Konto ohne guten Stand 403 ACCOUNT_SUSPENDED und ein Tarif, der den Endpunkt nicht abdeckt, 403 PLAN_REQUIRED. Eine Anfrage, die alle drei besteht, wird beantwortet. 401 heißt: anderen Schlüssel versuchen; 403 heißt: der Schlüssel ist in Ordnung, dieser Aufrufer ist nicht berechtigt.

Wo das beschrieben ist

Authentifizierung/de/authentication Fehler und Gründe/de/errors

Eine Kopie aktuell halten

Sie müssen den Katalog nicht neu laden, um zu wissen, dass Ihre Kopie aktuell ist. Speichern Sie den erhaltenen ETag, senden Sie ihn zurück, und ein unveränderter Datensatz antwortet mit 304 ohne Body - eine Antwort, die einen Platz im Ratenlimit kostet und nichts von Ihrem Tageskontingent.

DiagrammEine vorhandene Kopie prüfen

100%

sequenceDiagram
  participant C as Your copy
  participant A as GunSpec API
  C->>A: GET a record
  A-->>C: 200, with an ETag
  Note over C: keep the body and the ETag
  C->>A: The same request, If-None-Match
  A-->>C: 304 Not Modified, no body
  Note over A: one rate-limit slot, and nothing<br/>off your daily allowance

Eine vorhandene Kopie prüfenDie erste Anfrage liefert den Datensatz mit einem ETag, den Sie neben dem Body aufbewahren. Beim nächsten Abruf desselben Datensatzes senden Sie diesen ETag als If-None-Match zurück: hat sich nichts geändert, erhalten Sie 304 Not Modified ganz ohne Body. Diese Antwort kostet einen Platz im Minutenlimit und nichts von Ihrem Tageskontingent - eine Kopie aktuell zu halten ist also günstiger, als sie neu zu laden.

Wo das beschrieben ist

Caching und Aktualisierung/de/caching Firearms-Endpunkte/de/api/firearms

Woher ein Datensatz kommt

Ein Datensatz wird geschrieben und geprüft, bevor er veröffentlicht wird, und unsere Prüfungen entscheiden, ob er überhaupt ausgeliefert wird. Mit der Veröffentlichung ändern sich seine Version und sein Änderungsdatum - die beiden Werte, gegen die Sie eine zwischengespeicherte Kopie halten können.

DiagrammWas ein veröffentlichter Datensatz durchlaufen hat

100%

flowchart LR
  record["A record is written<br/>and reviewed"] --> checks{"Checks pass?"}
  checks -->|"no"| held["Held back, not published"]:::fail
  checks -->|"yes"| published["Published to the catalog"]:::ok
  published --> stamp["Its version and date move"]
  stamp --> api["REST API"]
  api --> sdk["TypeScript and Python SDKs"]
  api --> mcp["Hosted MCP server"]

Was ein veröffentlichter Datensatz durchlaufen hatEin Datensatz wird geschrieben und geprüft, bevor er veröffentlicht wird, und er wird nur veröffentlicht, wenn unsere Prüfungen bestehen - was durchfällt, wird zurückgehalten statt ausgeliefert. Mit der Veröffentlichung ändern sich Version und Änderungsdatum des Datensatzes: die beiden Werte, gegen die Sie eine zwischengespeicherte Kopie vergleichen können. Die REST-API liefert das Veröffentlichte, und die SDKs und der gehostete MCP-Server liefern, was die API liefert.

Wo das beschrieben ist

Wie das ehrlich gehalten wird/de/verified Datenqualität/de/quality/overview

Wie eine Änderung Sie erreicht

Niemand pollt für Sie. Eine Änderung an einem Datensatz wird festgehalten und binnen fünfzehn Minuten weitergegeben, abgeglichen mit den von Ihnen abonnierten Ereignissen - sie erreicht Sie also auch dann, wenn Ihr Endpunkt gerade nicht erreichbar war, denn eine fehlgeschlagene Auslieferung wird wiederholt und danach für Ihren erneuten Anstoß aufbewahrt.

DiagrammWie eine Änderung Ihren Endpunkt erreicht

100%

flowchart LR
  change["A record changes"] --> recorded["Recorded, and sent on<br/>within 15 minutes"]
  recorded --> matched["Matched to your subscriptions"]
  matched --> post["Signed POST to your endpoint"]
  post --> ok{"Your endpoint answers 2xx?"}
  ok -->|"yes"| done["Delivered"]:::ok
  ok -->|"no"| retry["Retried at 1, 5 and 15 minutes"]:::warn
  retry --> post
  retry --> still{"Still failing?"}
  still -->|"yes"| failed["Left failed, yours to replay"]:::fail

Wie eine Änderung Ihren Endpunkt erreichtÄndert sich ein Datensatz, wird die Änderung festgehalten und binnen fünfzehn Minuten weitergegeben - Sie müssen nicht pollen. Sie wird mit den von Ihnen abonnierten Ereignissen abgeglichen, und jeder passende Endpunkt erhält ein signiertes POST. Eine 2xx-Antwort schließt die Auslieferung ab; alles andere wird nach einer, fünf und fünfzehn Minuten erneut versucht, und was danach weiter fehlschlägt, bleibt als fehlgeschlagen stehen, damit Sie es prüfen und erneut anstoßen können.

Wo das beschrieben ist

Webhooks für Datenänderungen/de/webhooks Webhook-Endpunkte/de/api/me-webhooks

Ein Assistent ruft die API

Der gehostete MCP-Server hält keine Daten und keine eigenen Zugangsdaten: er leitet Ihren Schlüssel weiter und markiert den Aufruf als MCP-Aufruf. Diese Markierung kann Ihre Limits nur senken - genau das macht das kleinere MCP-Kontingent innerhalb Ihres Tarifs möglich.

DiagrammEin Werkzeugaufruf über den gehosteten MCP-Server

100%

flowchart LR
  agent["Your assistant"] --> server["Our MCP server"]
  server --> key["Forwards your own API key"]
  key --> api["REST API"]
  api --> plan{"Plan's daily allowance left?"}
  plan -->|"no"| capped["Refused: 429 DAILY_CAP_EXCEEDED"]:::fail
  plan -->|"yes"| sub{"MCP allowance left?"}
  sub -->|"no"| mcpcap["Refused: 429 MCP_DAILY_CAP_EXCEEDED"]:::fail
  sub -->|"yes"| answer["Answered, and counted<br/>as one request"]:::ok

Ein Werkzeugaufruf über den gehosteten MCP-ServerIhr Assistent ruft unseren MCP-Server, der keine Daten und keine eigenen Zugangsdaten hält: er leitet Ihren API-Schlüssel weiter und ruft dieselbe REST-API auf, die Sie auch aufrufen würden. Zuerst wird das Tageskontingent Ihres Tarifs geprüft und mit DAILY_CAP_EXCEEDED abgelehnt, dann das kleinere MCP-Kontingent darin mit MCP_DAILY_CAP_EXCEEDED. Ein Aufruf, der beides besteht, wird beantwortet und als eine Anfrage Ihres Tarifs gezählt.

Wo das beschrieben ist

MCP-Überblick/de/mcp/overview MCP-Limits/de/mcp/limits

Warum die Beispiele funktionieren

Das Snippet auf einer Referenzseite ist keine Illustration. Die CI installiert das veröffentlichte SDK, führt genau dieses Snippet gegen die Produktion aus und veröffentlicht das Ergebnis - Erfolge wie Fehler. Genau das meldet das Abzeichen unter jedem Beispiel.

DiagrammWie ein abgedrucktes Beispiel belegt wird

100%

flowchart LR
  page["A docs page<br/>prints a sample"] --> run["We run that sample<br/>against production"]
  run --> result{"Did it work?"}
  result -->|"yes"| pass["Recorded as passed"]:::ok
  result -->|"no"| fail["Recorded as failed"]:::fail
  pass --> badge["Shown under the sample"]
  fail --> badge

Wie ein abgedrucktes Beispiel belegt wirdEine Doku-Seite druckt ein Beispiel. Wir installieren das veröffentlichte SDK in ein frisches Projekt, schreiben das Beispiel genau so, wie die Seite es zeigt, und führen es gegen die Produktion aus. Ob es bestanden oder fehlgeschlagen ist, wird in jedem Fall festgehalten, und dieser letzte echte Lauf ist das, was das Abzeichen unter dem Beispiel und die Prüfseite anzeigen - ein Beispiel, das nicht mehr funktioniert, sagt das also, statt in Ordnung auszusehen.

Wo das beschrieben ist

Beispielprüfung/de/api/verification Endpunkt-Status/de/api/health