API Gateway Übersicht

Der istCHAMPREPAPI Gateway der öffentliche Einstiegspunkt für unterstützte Plattformintegrationen. Er validiert Anmeldeinformationen, überprüft Gültigkeitsbereiche und den Dienstzugriff, setzt aktuelle Nutzungskontrollen durch und leitet akzeptierte Anfragen an den entsprechenden CHAMPREPDienst weiter.

Basis-URL

https://api.champrep.com/v1

Die kuratierten öffentlichen Routen werden unter /v1. Verwenden Sie in Serveranwendungen die vollständige HTTPS-URL und nutzen Sie die Umgebungskonfiguration, anstatt die Basis-URL über Ihren gesamten Code zu verstreuen.

Erste authentifizierte Anfrage

Erstellen Sie einen bereichsgebundenen Schlüssel unter API Schlüssel, und übergeben Sie diesen anschließend als „Bearer“-Anmeldeinformation:

curl --fail-with-body \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Accept: application/json" \
  https://api.champrep.com/v1/auth/whoami

Legen Sie niemals einen echten Schlüssel in der Quellcodeverwaltung, einem Browser-Bundle, einer mobilen Binärdatei, einer Support-Nachricht oder in der Dokumentation ab. Verwenden Sie für bereitgestellte Integrationen einen serverseitigen Geheimnismanager.

Anforderungskonventionen

• Senden und akzeptieren Sie JSON, sofern ein Endpunkt nicht ausdrücklich einen anderen Medientyp angibt.
• Verwenden Sie ISO-8601-Zeitstempel mit einer expliziten Zeitzone für Datums- und Zeitwerte.
• Führen Sie eine URL-Kodierung der Pfad- und Abfrageparameter durch.
• Behalten Sie die „Bearer“-Anmeldeinformationen im Authorization Header.
• Behandeln Sie Identifikatoren als undurchsichtige Zeichenfolgen; leiten Sie deren Format nicht ab und erstellen Sie sie nicht lokal.
• Verwenden Sie die kuratierten /v1 Routen in der Referenz der Service-Endpunkte.

Offizielle Dienste könnenSDKs Gateway-Kompatibilitätsrouten nutzen, während ein Dienst auf einen kuratierten Dienst migriert wird /v1 Vertrag. Diese Kompatibilitätsschicht ist für die SDK; neue direkte Integrationen sollten keine backend-privaten Pfade aus dem Browser- Datenverkehr oder aus internen SystemenSDK kopieren.

Antwort-Envelopes

Erfolgreiche, vom Gateway zusammengestellte Antworten haben folgende Struktur:

{
  "success": true,
  "data": {}
}

Gateway-Fehler werden durch diese Form dargestellt:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A safe explanation of the error.",
    "status": 400
  }
}

Einige Antworten von über einen Proxy weitergeleiteten Diensten behalten ihren dienstspezifischen Datenumschlag bei. Überprüfen Sie stets zuerst den HTTP-Status und lesen Sie dann success, dataoder error sofern vorhanden. Siehe Fehler, Limits und Wiederholungsversuche für portable Fehlerbehandlung.

Authentifizierungs- und Autorisierungsablauf

Jede Serviceanfrage wird der Reihe nach ausgewertet:

1. Das Gateway überprüft den SchlüsselAPI sowie alle konfigurierten IP-Einschränkungen.
2. Das aktuelle Gateway-Nutzungsfenster ist markiert.
3. API Gateway wird für den aktiven Tarif und das aktuelle Profil überprüft.
4. Der Zugriff auf den Ziel-Dienst wird überprüft.
5. Der Geltungsbereich des Schlüssels wird mit der Route und der HTTP-Methode abgeglichen.
6. Der Ziel-Dienst führt eigene Überprüfungen hinsichtlich Rolle, Organisation, Ressource und Kontingent durch.

A 403 kann daher bedeuten, dass der Schlüssel zwar gültig ist, der aktive Geltungsbereich, die Rolle, der Dienstzugriff, der Tarif, die Organisationsrichtlinie oder die Ressourcenberechtigung den Vorgang jedoch nicht zulassen.

Versionierung

Das erste URL-Segment ist die APIHauptversion. Zusätzliche Antwortfelder und neue Endpunkte können innerhalb einer Hauptversion auftreten. Integrationen sollten unbekannte Felder ignorieren und sich nicht auf undokumentierte Felder oder deren Reihenfolge verlassen.

Verwenden GET /v1/version für Informationen zur öffentlichen Gateway-Version. Planen Sie Migrationen auf eine zukünftige Hauptversion explizit, anstatt den Code umzuschreiben /v1 Pfade zur Laufzeit.

Nächste Schritte

• Erstellen Sie einen Schlüssel mit minimalen Berechtigungen.
• Wählen Sie eine Serviceroute aus.
• Umgang mit Limits und Fehlern.
• Verwenden Sie Webhooks anstelle von häufigen Abfragen.
• Bevorzugen Sie Terminal-Workflows? Installieren Sie die CHAMPREPCLI.