Authentifizierung
118 der 135 Operationen brauchen einen API-Schlüssel. Zwei Header tragen ihn, jeder Plan beginnt kostenlos, und ein abgelehntes Credential sagt genau warum.
Zwei Wege, einen Schlüssel zu senden
Beide Header tragen denselben Schlüssel und beide sind kanonisch: Keiner wird abgeschafft. Sendest du beide, gewinnt X-API-Key. Der Schemaname wird ohne Groß-/Kleinschreibung verglichen.
X-API-Key: <key>
Der einfache Header. Das, was Playground und die curl-Beispiele dieser Referenz senden.
cURL
curl -H "X-API-Key: your_api_key" \ https://api.gunspec.io/v1/firearmsAuthorization: Bearer <key>
Das, was die generierten SDKs und die meisten HTTP-Clients standardmäßig senden. Das Token ist derselbe Schlüssel.
cURL
curl -H "Authorization: Bearer your_api_key" \ https://api.gunspec.io/v1/firearmsSende einen Schlüssel nur über TLS und nur aus serverseitigem Code; die Seite Sicherheit behandelt die Hygiene.
Was einen Schlüssel braucht
118 Operationen brauchen ein Credential; 19 antworten ohne.
118 Operationen brauchen einen Schlüssel
Der ganze Katalog: Waffen, Suche, Vergleich, Hersteller, Kaliber, Munition, Statistiken sowie alle Konto- und Händler-Endpunkte. Ein Aufruf ohne Schlüssel ist ein 401, nie eine reduzierte Antwort.
19 sind offen
Inhalte, eine geteilte Sammlung, die zwei Health-Probes, die Spezifikation selbst und ihre Swagger-UI: für jeden lesbar.
- GET
/v1/out/{clickId} - GET
/v1/ammunition/{id}/bullet.svg - GET
/v1/data/gaps - GET
/v1/data/tasks - GET
/v1/data/tasks/{taskKey} - GET
/v1/data/gaps/history - GET
/v1/changelog - GET
/v1/changelog/{id} - GET
/v1/notices - GET
/v1/sdk/verification - GET
/v1/examples/verification - GET
/v1/contract - GET
/v1/blog - GET
/v1/blog/{slug} - GET
/v1/collections/{shareId} - GET
/health - GET
/ready - GET
/openapi.json - GET
/docs
Die letzten beiden liefert die API, sie sind aber keine Operationen der Spezifikation; die Health-Probes sind es und antworten ohne Schlüssel mit 200 oder 503.
Was ein Schlüssel freischaltet
Ein Schlüssel trägt seinen Plan. Der Plan entscheidet, welche Endpunkte antworten, wie viele Felder zurückkommen, wie tief eine Liste geblättert werden kann und wie viele Anfragen pro Minute und Tag erlaubt sind.
- ExplorerKostenlos. Die Listen-Endpunkte mit reduziertem Feldsatz, fünf Seiten tief, verborgene Gesamtzahlen.
- BuilderVolle Spezifikationen, Suche, Vergleich, Bild- und 3D-Modell-URLs, Game-Stats.
- StudioJeder Endpunkt inklusive Kompatibilitäts-Engine, Webhooks, unbegrenztes Blättern.
- EnterpriseStudio plus Händlereintrag, die höchsten Limits, ein SLA und dedizierter Support.
Schlüssel erstellen, rotieren und widerrufen
Schlüssel liegen in deinem Profil auf der Hauptseite. Ein Schlüssel wird einmal bei der Erstellung gezeigt; speichere ihn dann.
- 1Auf gunspec.io anmelden und Profil, dann API-Schlüssel öffnen.
- 2Einen Schlüssel pro Anwendung oder Umgebung erstellen und so benennen, dass du später weißt, was du widerrufst.
- 3Planmäßig rotieren: neuen Schlüssel erstellen, ausrollen, dann den alten widerrufen. Der Widerruf wirkt sofort.
- 4Einen Schlüssel deaktivieren, um ihn zu pausieren, ohne Namen und Verlauf zu verlieren; ein deaktivierter Schlüssel antwortet
401 KEY_DISABLED.
Wenn ein Schlüssel abgelehnt wird
Ein 401 betrifft immer das Credential, und error.reason nennt das Problem. Ein 403 heißt, der Schlüssel ist in Ordnung und Plan oder Konto sind nicht berechtigt; ein neuer Schlüssel ändert daran nichts.
AUTH_REQUIREDThis endpoint needs a credential and none was sent.KEY_MISSINGNo API key was sent.KEY_INVALIDThe API key is not one we issued, or it has been deleted.KEY_DISABLEDThe key was switched off by the account that owns it.KEY_EXPIREDThe key has passed its expiry date.
Im Playground ausprobieren
Jede Endpunktseite hat eine Try-It-Konsole. Einen Schlüssel einmal einfügen; er bleibt nur in diesem Browser, wird bei jeder Anfrage aus der Konsole als X-API-Key gesendet und von uns nie gespeichert.