Die Cornerstone Data Exporter API (DEAPI) und die Throttle-Limits, vor denen Dich niemand warnt

Beim ersten Mal, als wir ein komplettes Learning Transcript über die Data Exporter API aus Cornerstone OnDemand (CSOD) gezogen haben, lief alles wunderbar. Also haben wir es noch einmal gemacht. Und noch einmal. Irgendwo beim vierten Durchlauf hörte Cornerstone auf, höflich zu sein, und begann, 429 Too Many Requests zurückzugeben. Keine Warnung, keine Schonfrist. Einfach eine Wand.

Wenn Du schon einmal etwas gegen die Cornerstone Data Exporter API gebaut hast, kennst Du diese Wand. Das hier ist der Leitfaden, den wir uns gewünscht hätten, bevor wir dagegen gelaufen sind – geschrieben für HRIS-Analysten, Integration Engineers und People-Analytics-Leute, die ihre Cornerstone-Daten raus und in Bewegung brauchen und die Rate Limits lieber nicht auf die harte Tour lernen wollen.

Wir ersparen Dir ein paar haarsträubende Nächte.

Was die DEAPI eigentlich ist (und was nicht)

CSOD bietet Dir drei Hauptwege, um Daten herauszubekommen, und sie werden ständig durcheinandergebracht.

• Die REST API ist Echtzeit und liefert Dir reichhaltige, verschachtelte Objekte für einen einzelnen User oder Datensatz. Perfekt für „zeig mir genau diese eine Person, jetzt sofort“.
• Die Data Exporter API, kurz DEAPI, ist das Arbeitstier für Massendaten. Sie spricht OData, Du filterst also mit $filter, wählst Spalten mit $select und paginierst mit $top. Sie ist für breite Abfragen über Tausende von Datensätzen gebaut und unterstützt Delta-Sync, sodass Du nur das ziehst, was sich geändert hat.
• Die Reporting API (RAPI) sitzt auf den älteren Reporting-Views auf. Sie hat noch ihre Berechtigung, ist aber nicht der Ort, an dem neue Integrationen ansetzen sollten. Cornerstone selbst nennt den Data Exporter den spirituellen Nachfolger von RAPI und sagt: „over time, we will start to deprecate RAPI endpoints if the same data can be retrieved via DEAPI.“ Die Plattform bewegt sich in Richtung DEAPI. Geh mit.

Zwei Dinge bei der DEAPI bringen alle zu Fall.

Erstens: Sie ist read-only. Du kannst darüber nichts zurückschreiben. Wenn Du ein Transcript erstellen oder aktualisieren musst, ist das ein Job für REST.

Zweitens: Die DEAPI nutzt die numerische user_id, während die REST API employeeRef, den externen ID-String, verwendet. Die beiden sind nicht austauschbar. Wir haben schon zugesehen, wie kluge Leute einen ganzen Vormittag verloren haben, weil sie einen DEAPI-Call mit einer REST-artigen ID gefiltert und dafür eine saubere, selbstbewusste, komplett leere Antwort bekommen haben.

REST vs. Reporting API vs. DEAPI: welche wann

Weil diese drei ständig durcheinandergeraten, hier die ganze Entscheidung in einer Tabelle.

Kurz gesagt:

• Musst Du etwas schreiben, oder brauchst Du die Daten einer Person genau jetzt? Dann REST.
• Brauchst Du breite, umfangreiche oder historische Daten über viele Personen hinweg – der Stoff, aus dem Dashboards, Exporte und Data Warehouses gemacht sind? Dann DEAPI.
• Bist Du noch auf RAPI? Das funktioniert heute noch, aber plane Deinen Umzug zur DEAPI, denn Cornerstone geht denselben Weg.

Die komplette Übersicht über jeden Weg aus Cornerstone hinaus – REST, Reporting API, Data Exporter und Bulk – und wann Du zu welchem greifst, findest Du unter Daten aus Cornerstone herausbekommen.

Die Throttle Limits, in echten Zahlen

Das ist der Teil, für den Du in der Dokumentation graben musst. Das sind die Obergrenzen, gegen die Du arbeitest.

Die Foundational (REST) APIs teilen sich ein generisches Budget von 417 Anfragen pro Minute, 25.000 pro Stunde und 600.000 pro Tag – das sagt Cornerstone direkt so in seinem Throttling-Guide.

Zwei Dinge dazu, wie dieses Budget gezählt wird, denn genau die bringen Leute rein. Erstens gelten die Limits pro Umgebung: Cornerstone sagt unmissverständlich, dass „throttle limits are for each environment“ gelten, sodass Dein Pilot-, Stage- und Produktions-Portal jeweils ihr eigenes Budget bekommen. Zweitens werden sie auf Endpoint-Ebene getrackt – die Throttling-Header sind urilevel-Header, und die Pro-Minute-Zahl ist einfach das Stunden-Limit geteilt durch sechzig. Das ist also kein Quota pro User oder pro Token, dem Du durch mehr Credentials entkommen könntest. Alles, was auf einen bestimmten Endpoint in einem bestimmten Portal trifft, zieht aus demselben Topf, was bedeutet, dass Dein tatsächlicher Spielraum davon abhängt, was sonst noch mit diesem Portal spricht – andere Integrationen, andere Admins, ein geplanter Report, der zum falschen Zeitpunkt losläuft – nicht nur von Deinem eigenen Code.

Die Data Exporter API läuft mit einem deutlich engeren Pro-Minute-Budget – in der Größenordnung von 120 Calls pro Minute pro Portal, dokumentiert in Cornerstones Data Exporter API Guide. Das ist die Zahl, die den meisten zum Verhängnis wird. Sie klingt nach viel, bis Du Dich durch ein großes Transcript-Objekt paginierst und im Sekundenbruchteil-Takt Calls abfeuerst. Du erreichst sie schneller, als Du denkst.

Cornerstone sagt Dir immerhin, wo Du stehst, in zwei dokumentierten Response-Headern neben den Limits: x-csod-throttling-rate-limit-urilevel (Deine stündliche Obergrenze) und x-csod-requests-remaining-urilevel (was Dir noch bleibt). Behalte die verbleibende Zahl im Blick und drossle Dich selbst, bevor Cornerstone es für Dich tut. Ein 429 ist keine Katastrophe, aber selbst zu bremsen ist besser, als mitten im Job rausgeworfen zu werden.

Und manchmal hat die Wand überhaupt nichts mit Deinem Rate-Budget zu tun – Cornerstone selbst hat einfach einen schlechten Morgen. Wenn Calls auf eine Art fehlschlagen, die nicht nach Throttling aussieht, schließe zuerst die einfachste Ursache aus. Wir betreiben eine kostenlose Live-Statusseite für jede Cornerstone-Umgebung weltweit, die jede Minute aktualisiert wird – genau für diesen „liegt's an mir oder an denen?“-Moment.

Die 15-Minuten-Verzögerung, die Dir in einem Meeting peinlich wird

Die DEAPI wird von Cornerstones Echtzeit-Data-Warehouse gespeist, und „Echtzeit“ kommt hier mit einem Sternchen. In Produktion solltest Du mit rund 15 Minuten Verzögerung rechnen, zwischen dem, was im Portal passiert, und dem, was in einer DEAPI-Abfrage auftaucht. Auf Demo- und Staging-Portalen kann das Stunden dauern, manchmal mehr.

Für das meiste, wofür die DEAPI gebaut ist, spielt das kaum eine Rolle. Headcount-Trends, Completion Rates, Abteilungsaufschlüsselungen, jede aggregierte Sicht über Tausende von Personen – eine Verzögerung von fünfzehn Minuten ist da unsichtbar, weil sich das große Bild nicht minütlich bewegt, und ein nächtlicher Sync kümmert sich noch weniger darum. Wo die Verzögerung wirklich zubeißt, ist der individuelle Echtzeit-Moment: Jemand schließt einen Kurs ab, aktualisiert die Seite in der Erwartung, es zu sehen, und es ist noch nicht da. Das ist ein Job für die REST API, nicht für die DEAPI. Greifst Du zur falschen, verbringst Du zehn Minuten damit, einem Raum Data Warehouses zu erklären, der nicht gefragt hat. Wisse also, welche Frage Du gerade beantwortest – den Überblick oder die einzelne Aktion – und baue die Verzögerung in alles ein, was Du den Leuten versprichst.

Die Stolperfallen, die echte Zeit kosten

Ein paar weitere Dinge, die wir gelernt haben, indem wir sie falsch gemacht haben.

Achte auf den Fan-out pro Datensatz. Der teuerste Fehler, den wir sehen, ist Code, der einen REST-Endpoint einmal pro Datensatz aufruft – einmal pro Learning Object oder einmal pro User – nur um eine Liste anzureichern. Bei einem großen Katalog sind das Tausende Calls, wo eine Handvoll gut geschnittener Bulk-Abfragen genügen würde, und es ist der schnellste Weg, den wir kennen, um ein Rate-Budget für nichts zu verbrennen. Wenn Du Dich dabei ertappst, einen API-Call pro Datensatz in einer Schleife aufzurufen, halt inne und finde zuerst den Bulk-Weg.

Statusfelder sind numerische Codes, keine Klartext-Labels. Ein Transcript-Status kommt als "64" zurück, nicht als „Completed“. Ein User-Status von "1" bedeutet Active. Die Codes sind konsistent, aber Du musst sie selbst mappen, und das Nummerierungsschema ist nicht immer intuitiv – behandle also jedes Statusfeld als opaken String und übersetze ihn explizit.

Was es wirklich braucht, um innerhalb der Limits zu bleiben

Nichts davon macht die DEAPI schlecht. Sie ist schnell, gut strukturiert, und das zugrunde liegende Design ist wirklich gut. Es bedeutet nur, dass Deine Daten zuverlässig herauszubekommen ein echter, laufender Engineering-Job ist – kein Skript, das Du einmal schreibst und dann vergisst.

Es richtig zu machen bedeutet, mindestens:

• Nur das synchronisieren, was sich geändert hat, statt bei jedem Lauf das ganze Portal neu zu ziehen.
• Jede Anfrage auf die Limits zuschneiden – die richtigen Batch-Größen, die richtige Paginierung, und wissen, wo die Obergrenzen liegen, bevor Produktion sie für Dich findet.
• Sauber abbremsen, wenn Du Dich dem Limit näherst, und sauber wieder aufstehen von den 429ern, die Du trotzdem gelegentlich bekommst.
• Cornerstones Rohformat übersetzen – die numerischen Codes, die ID-Diskrepanzen, die lokalisierten Felder – in etwas, das Deine Dashboards und Dein BI-Tool tatsächlich lesen können.
• Die stabilen Daten cachen, damit Du Cornerstone nicht bei jedem einzelnen Lauf dieselbe Frage stellst.
• Das Ganze überwachen, denn wenn ein Sync sich still und leise ins Hintertreffen bringt, willst Du das erfahren, bevor es der Vorstand tut.

Jeder einzelne dieser Punkte ist sein eigenes kleines Kaninchenloch. Zusammen sind sie ein System, das jemand verantworten muss – und zwar dauerhaft, durch jedes Cornerstone-Release, jede Schema-Änderung und jedes neue Modul, das Du aktivierst.

Der ehrliche Teil

Hier ist der Punkt: Alles, was wir gerade durchgegangen sind, ist Arbeit. Echte, laufende Arbeit, für die jemand verantwortlich sein muss. Rate-Limit-Handling, Berechtigungs-Jonglage, Status-Code-Mapping, die 15-Minuten-Verzögerung, die Retry-Logik, die Paginierung. Es ist die Art von Arbeit, die unsichtbar ist, solange sie läuft, und sehr sichtbar wird, wenn sie ausfällt – meistens genau in der Woche, in der Du im Urlaub bist.

Wir hatten es satt, das für jeden Kunden immer wieder neu zu schreiben, also haben wir octo.taxi gebaut, um es einmal zu machen – und zwar richtig. Es synchronisiert Deine Cornerstone-Daten über die DEAPI, kümmert sich um Throttling, Delta-Logik und Retries, und liefert Dir saubere, aktuelle Daten mit Dashboards, einem Organigramm, Abfragen in normaler Sprache und einer eigenen REST API. Keine 429er. Keine Scope-Rechnerei. Kein Data-Warehouses-Erklären für den Vorstand.

Du solltest nicht zum Rate-Limit-Experten werden müssen, nur um Deine eigenen Zahlen zu sehen. Wenn Du aber direkt gegen die DEAPI bauen willst, hoffen wir, dass Dir das die Wand erspart hat, gegen die wir gelaufen sind.

So oder so – Deine Daten sollten sich frei bewegen, von A nach B, mit Stil.

---

Quellen. Cornerstones eigene Entwicklerdokumentation, für alle, die die Zahlen nachprüfen wollen: API-Throttling-Limits & Header · Data Exporter API Guide · Reporting API Considerations (DEAPI als Nachfolger von RAPI).