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 Standard-HTTP-Antwortcodes, Authentifizierung und Verben.

Ihre Reach 360-API-Anfragen verwenden die URL https://api.reach360.com. 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 verwendet, um Anfragen zu authentifizieren und Ihr Reach 360-Konto zu identifizieren. Es sollte sicher aufbewahrt werden: Stellen Sie sicher, dass es nicht der Versionskontrolle unterliegt und dass nur diejenigen darauf zugreifen können, die es benötigen. Behandeln Sie es wie jedes andere Passwort.

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

Versionierung

Wenn Änderungen an unserer API vorgenommen werden, die nicht abwärtskompatibel sind, veröffentlichen wir eine neue, veraltete API-Version. Die ursprüngliche API-Version von2023-04-04 wird angenommen, wenn Ihre Anfragen keinenAPI-Version Header enthalten.

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

Wann immer eine neue API-Version veröffentlicht wird, nennen wir sie explizit 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: 16.07.2020“

Seitennummerierung

Alle paginierten Endpunkte sind cursorbasiert und geben einenextUrl Eigenschaft zurück. Wenn nichtnull,nextUrl bedeutet dies, dass möglicherweise zusätzliche Ergebnisse vorliegen. EineGET Anfrage an dienextUrl URL kann gestellt werden, um die nächste Seite mit Ergebnissen zu erhalten. AnextUrl vonnull gibt an, dass keine weiteren Ergebnisse vorliegen. Alle paginierten Endpunkte support einenlimit Abfragezeichenfolgenparameter, der die maximale Anzahl von Ergebnissen angibt, die in einer einzelnen Antwort zurückgegeben werden sollen. Alle Endpunkte, die eine Ergebnisliste zurückgeben, support Paginierung.

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

Endpunkte, 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

Irrtümer

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

  • validation_failed: Der Anfragetext hat einen Validierungsfehler
  • invalid_email: Dieemail Unterkunft ist keine korrekt formatierte E-Mail-Adresse
  • missing_api_key: Der Anfrage fehlt ein API-Schlüssel
  • invalid_api_key: Der angegebene API-Schlüssel ist ungültig

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 helfen, benutzerdefinierte Skripts zu schreiben oder Anwendungen von Drittanbietern zu debuggen.

Wenn Sie auf ein Problem stoßen, werden wir unser Bestes tun, um Ihnen bei der Fehlerbehebung zu helfen, indem wir nach Folgendem fragen:

  • Die einfachste Version des Aufrufs, 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), Anforderungstexte und Antworttexte

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