Browse Articles

Browse Articles

Reach 360: Einführung in die Reach 360-API

Letzte Aktualisierung des Artikels:

Dieser Artikel gilt für:

Reach 360

Die Reach 360-API ist rund um REST organisiert. Unsere API verfügt über vorhersehbare ressourcenorientierte URLs, akzeptiert JSON-kodierte Anfragetexte, gibt JSON-kodierte Antworten zurück und verwendet standardmäßige HTTP-Antwortcodes, Authentifizierung und Verben.

Die neuesten Updates finden Sie im Changelog.

Klicken Sie hier, um zu erfahren, wie Sie API-Schlüssel in Reach 360 generieren.

Authentifizierung

Ihr API-Schlüssel wird zur Authentifizierung von Anfragen verwendet und identifiziert Ihr Reach 360-Konto. Es sollte sicher gespeichert werden: Stellen Sie sicher, dass es außerhalb der Versionskontrolle aufbewahrt wird und dass nur diejenigen darauf zugreifen können, die es benötigen. Behandle es wie jedes andere Passwort.

Alle API-Anfragen müssen die Bearer-Authentifizierung verwenden: Ihr API-Schlüssel muss als Bearer-Token im Authorization Header angegeben werden. Alle API-Anfragen müssen über HTTPS gestellt werden. Aufrufe über einfaches HTTP schlagen fehl. API-Anfragen ohne Authentifizierung schlagen ebenfalls fehl.

Versionierung

Wenn an unserer API Änderungen vorgenommen werden, die nicht abwärtskompatibel sind, werden wir eine neue, veraltete API-Version veröffentlichen. Wenn Ihre Anfragen keinen Header enthalten, 2023-04-04 wird von der ursprünglichen API-Version von ausgegangen. API-Version

Wenn ein ungültiger API-Versionsheader angegeben wird, erhalten Sie eine 400-Antwort mit dem Fehlercodeinvalid_api_version. Erfolgreiche API-Anfragen enthalten einen API-Version Antwort-Header, der angibt, mit welcher API-Version Ihre Anfrage bearbeitet wurde.

Immer wenn eine neue API-Version veröffentlicht wird, nennen wir sie ausdrücklich in unserem Changelog und erstellen zusätzlich einen neuen Eintrag auf der Seite API-Versionen.

Beispiel für eine Anfrage

curl -i < https://api.reach360.com/users >\\ 
 -H „Autorisierung: Träger $API_KEY“ -H „API-Version: 2020-07-16"

Seitennummerierung

Alle paginierten Endpunkte sind cursorbasiert und geben eine Eigenschaft zurück. nextUrl Wenn nichtnull, nextUrl deutet dies darauf hin, dass möglicherweise weitere Ergebnisse vorliegen. An die nextUrl URL kann eine GET Anfrage gestellt werden, um die nächste Ergebnisseite abzurufen. A nextUrl von null bedeutet, dass es keine weiteren Ergebnisse gibt. Alle paginierten Endpunkte support einen limit Abfragezeichenfolgenparameter, der die maximale Anzahl von Ergebnissen angibt, die in einer einzigen Antwort zurückgegeben werden sollen. Alle Endpunkte, die eine Ergebnisliste zurückgeben, support Paginierung.

Hinweis: Der limit Wert muss zwischen 1 und 100 liegen (sofern nicht anders angegeben; der Standardwert ist 50, falls nicht angegeben).

Endgeräte, die Paginierung unterstützen

  • GET /courses
  • GET /groups
  • GET /groups/{groupId}/users
  • GET /invitations
  • GET /learning-paths
  • GET /learning-paths/{learningPathId}
  • GET /learning-paths/{learningPathId}/courses
  • GET /reports/activity
  • GET /reports/courses/{courseId}
  • GET /reports/learners/{userId}
  • GET /reports/learning-paths/{learningPathId}/courses
  • GET /reports/learning-paths/{learningPathId}/learners
  • GET /users
  • GET /users/{userId}/groups
  • GET /webhooks

Fehler

Eine 400-Antwort mit einer Liste von errors wird zurückgegeben, wenn die Anfrage nicht gültig ist. Zu den häufigsten Fehlercodes gehören:

  • validation_failed: Im Hauptteil der Anfrage ist ein Validierungsfehler aufgetreten
  • invalid_email: Bei der email Unterkunft handelt es sich nicht um eine korrekt formatierte E-Mail-Adresse
  • missing_api_key: In der Anfrage fehlt ein API-Schlüssel
  • invalid_api_key: Der angegebene API-Schlüssel ist ungültig
  • invalid_content_type: Die Anfrage fehlt/hat den falschen Inhaltstyp

Beispiel für eine Antwort

{
„errors“: [
{
„code“: „invalid_email“, 
 „message“: „\\" email\\“ muss eine gültige E-Mail sein“
}]}

Unterstützung

Wir freuen uns, dass Sie Reach 360 mit den Tools verbinden, die Sie am häufigsten verwenden. Der Support kann bestätigen, ob API-Aufrufe wie erwartet funktionieren, aber wir können nicht beim Schreiben von benutzerdefinierten Skripten oder beim Debuggen von Drittanbieteranwendungen helfen.

Wenn Sie auf ein Problem stoßen, werden wir unser Bestes tun, um Ihnen bei der Behebung zu helfen, indem wir Sie um Folgendes bitten:

  • Die einfachste Version des Anrufs, den Sie mit der API tätigen
  • Ob das Problem außerhalb Ihrer Anwendung repliziert werden kann
  • Anforderungsheader, Antwortheader (einschließlich des X-Request-ID-Headers), Anfragetexte und Antworttexte

Wenden Sie sich an unser Team und teilen Sie uns mit, was passiert. Wir werden es von dort aus übernehmen!