Railnova bietet seinen Kunden ein Allgemeines HTTP REST API auf Railnova-Daten an, die 24 Stunden am Tag zu den folgenden Bedingungen verfügbar ist.
Das Railnova - Allgemeine HTTP REST API ermöglicht externen Diensten die Interaktion mit Railnova-Ressourcen wie Betriebsstatus von Assets, Wartungsmaßnahmen, Interventionen, Zähler.
Dieses API wird in der Regel als Schnittstelle zu bestehenden CMMS-Systemen, ERPs, ECM-Systemen (Entity in Charge of Maintenance) und Business Intelligence-Systemen von Drittanbietern wie PowerBI, QlikSense, Tableau oder Looker verwendet.
Es wird von unserem Web-Frontend genutzt und kann sich im Laufe der Zeit ändern. Bitte überprüfe die unten stehenden Richtlinien für Änderungen.
Bitte berücksichtige, dass dieses API nicht für das Streaming großer Telematikdaten entwickelt wurde. Wenn du regelmäßig Telematikdaten abrufen oder zu Railfleet pushen möchtest, lies bitte diesen Artikel.
Authentifizierung
Die Authentifizierung erfolgt über Basic Authentication (über HTTPS) mit dem Namen und Passwort eines Railfleet-Benutzers. Wir empfehlen daher, für jede Schnittstelle einen eigenen Benutzer anzulegen, die über die Railfleet-API implementiert werden soll.
Solltest du keine Berechtigung haben, einen neuen Benutzer in Railfleet anzulegen, wende dich bitte an deinen Firmenadministrator.
Umgebungen
Environment: Production
Host: [your-company].railnova.eu
Entry point: api/
Protocol: HTTPS
URL example: https://[yourcompany].railnova.eu/api/
> Wichtig: Du musst [your-company] durch deinen Firmenschlüssel ersetzen. Diesen Schlüssel findest du in der URL, wenn du die Railnova-Plattform besuchst.
Environment: Test
Host: test.railnova.eu
Entry point: api/
Protocol: HTTPS
URL example: https://test.railnova.eu/api/
Paginierung
Der größte Teil unserer API REST-Schnittstelle ist paginiert, um die beste Leistung zu gewährleisten.
Paginierte Endpunkte geben standardmäßig 50 Elemente zurück. Du kannst zusätzliche Seiten mit dem Seitenparameter in deiner HTTPS-GET-Anfrage angeben.
Hinweis: Der Page-Parameter muss nicht angegeben werden, um die erste Seite des Ergebnisses zu erhalten. Wenn die Abfrageparameter-Seite nicht angegeben wird, setzt das System seinen Wert auf 1.
Die Kopfzeile der Ergebnisse enthält Informationen zum Seitenwechsel (https://tools.ietf.org/html/rfc8288) und sollte in etwa wie folgt aussehen* :
Link: <https://one.railnova.eu/api/counters/?page=3>; rel="next", <https://one.railnova.eu/api/counters/?page=2>; rel="previous", <https://one.railnova.eu/api/counters/?page=30>; rel="last", <https://one.railnova.eu/api/counters/?page=1>; rel="first"
*Das Beispiel enthält Zeilenumbrüche zur besseren Lesbarkeit.
Die möglichen Werte sind:
next | Die Link-Relation für die jeweils folgende Seite der Ergebnisse. |
first | Die Link-Relation für die erste Seite der Ergebnisse. |
prev | Die Link-Relation für die jeweils vorherige Seite der Ergebnisse. |
last | The link relation for the last page of results. |
Im Internet gibt es mehrere Ressourcen zur Analyse der Link-Header-Paginierung in einer Vielzahl von Programmiersprachen; hier sind einige von diesen:
Javascript: https://www.npmjs.com/package/parse-link-header
Verfügbare Inhalte & Beispiele
Die folgenden Endpunkte werden durch die Bedingungen der Railnova - Allgemeinen HTTP REST API abgedeckt:
Beschränkungen: https://one.railnova.eu/api/asset_restriction/
Betriebsstatus: https://one.railnova.eu/api/asset_operational_status/
Interventionen: https://one.railnova.eu/api/intervention/
Wartungsmaßnahmen: https://one.railnova.eu/api/maintenance/
Du kannst oben auf der Seite die Option "Pretty print" auswählen, um die API-Ergebnisse mit Zeilenumbrüchen anzuzeigen, damit sie leichter zu lesen sind.
Ohne "pretty print":
Mit "pretty print":
Ratenbeschränkung
Die Railnova - Allgemeine HTTP REST API ist ratenbegrenzt, um Nutzungsmissbrauch zu vermeiden. Die Beschränkungen sind wie folgt:
eine Burst-Geschwindigkeit von 50 Anfragen pro Minute
eine dauerhafte Geschwindigkeit von 360 Anfragen pro Stunde
Dieses Limit gilt pro Benutzer und für alle Endpunkte.
Bitte beachte, dass das Limit bei Verwendung der Burst-Geschwindigkeit nach 7,2 Minuten erreicht ist.
Beachte bei der Abfrage von Telematikdaten, dass jede Datenminute als eine Abfrage zählt. Die Grenzen für die Telematik-Endpunkte (flat_event und telematics/events) können daher schnell erreicht werden, wenn du eine große Menge an Daten abfragst.
Wenn du eine große Menge an Telematikdaten auf einmal benötigst, empfehlen wir dir, unseren in diesem Artikel beschriebenen Datenexport zu verwenden.
Wenn diese Grenze erreicht wird, erhalten alle nachfolgenden Anfragen eine 429 HTTP-Fehlerantwort mit der Information, wann die nächste erfolgreiche Anfrage akzeptiert wird.
Wenn diese Grenze für deine Nutzung zu niedrig ist, kontaktiere bitte unser Sales team.
Abkündigungsrichtlinien
Unter den Bedingungen der Railnova - Allgemeinen HTTP REST API möchten wir sicherstellen, dass unsere Kunden informiert werden und Zeit haben, ihre Systeme vor den Änderungen zu aktualisieren, während wir gleichzeitig die normalen Arbeitsabläufe der Feature- und Produktentwicklung bei Railnova ermöglichen.
Bei der Veröffentlichung einer neuen Version können bestimmte Funktionen aus früheren Versionen veraltet sein ("eine signifikante Änderung"). Bei der Freigabe von "Bruchänderungen" werden wir Benutzer vor dem Freigabedatum der "Bruchänderungen" benachrichtigen und die Rückwärtskompatibilität für 6 Monate sicherstellen.
Änderungen, die im Rahmen der Railnova-API als "brechend" gelten, sind:
Änderung der Benennung eines Endpunkts
Entfernung bestimmter Daten aus einem genutzten Endpunkt
Änderung der Geschwindigkeitsbegrenzung unserer API
Wir geben keine Garantien in Bezug auf die Railnova generic API auf:
das Hinzufügen neuer Endpunkte
das Hinzufügen zusätzlicher Informationen zu bestehenden Endpunkten
Um über Änderungen benachrichtigt zu werden, muss die Nutzung der API hier registriert werden: https://forms.gle/tNRDb82996PkKRk79
Support
Hast du noch Fragen? Dann geh auf die Railnova-Plattform und klick auf "Kontakt", um Hilfe zu erhalten!
