APIs und Webhooks zur Integration in externe Systeme
Unsere APIs sind REST-gestützt und verwenden json als Trägerformat. Für alle unsere APIs und Webhooks gibt es eine Open API 3.0.2-Spezifikation, die von unseren Integrationspartnern genutzt werden kann, um Modellgerüste mit Typprüfungen und API-Wrappern für unsere Endpunkte innerhalb ihrer Werkzeuge zu generieren.
Die API- und Webhook-Dokumentation wird aus diesen offenen API-Spezifikationen generiert und unseren Partnern im Rahmen des ioki Entwicklerprogramms zur Verfügung gestellt. Das ioki Entwicklerprogramm bietet auch Zugang zu einem gemeinsamen Bug-Tracker und spielt eine entscheidende Rolle bei der Kommunikation von API-Änderungen. Die Dokumentation besteht aus dem API Guide, Passenger API, Driver API, Platform API und Webhooks.
API Guide
Der API Guide enthält eine Anleitung zur korrekten Verwendung
Passenger API
Für die Entwicklung von vollwertigen DRT Fahrgast-Clients
Driver API
Stellt alle Elemente zur Verfügung, um einen Fahrer-Client zu schreiben
Platform API
Schnittstelle für die vollständige Integration mit fremden Backends
Webhooks
Informationen über Ereignisse, die im ioki Ökosystem stattfinden
Das Entwickler Programm
Die Teilnahme am ioki Entwicklerprogramm ist für die Integration unserer APIs notwendig.
Voraussetzung ist ein NDA (non-disclosure agreement) mit ioki: Abhängig von Ihrer Beziehung zu ioki wird Ihr Key Account Manager, Vertriebskontakt oder technischer Partner Sie gerne durch diesen einfachen Prozess führen. Das NDA wird auch benötigt, wenn Sie eine Anforderungsanalyse oder Machbarkeitsstudie durchführen und die Dokumentation mit Ihrem Team noch einmal überprüfen müssen. Sobald das NDA unterzeichnet ist, erstellen wir für Sie und Ihre Teammitglieder Konten für den Zugriff auf unsere GitLab-Instanz für Entwickler.
Über dieses Konto haben Sie Zugriff auf die neueste API-Dokumentation und den Bug-Tracker. Wir sind bei diesem Prozess sehr streng, da unsere APIs nicht öffentlich sind und aufgrund ihrer Komplexität in der Regel im Voraus geklärt werden müssen. Außerdem: Der Zugang zur Dokumentation und zum Bug-Tracker ist zwar der naheliegende Teil, aber das Entwicklerprogramm hat noch mehr zu bieten. Es zahlt sich aus, indem es die Prozesse optimiert.
Die Vorteile auf einen Blick
- Erhalten Sie Zugang zu unserer gesamten Dokumentation: API-Richtlinien, Passenger API, Driver API, Platform API und Webhook
- Zugang zu einem gemeinsamen Issue Tracker um über Fragen, Anfragen und Fehlerberichte auf dem Laufenden zu bleiben
- Technischer Support: verantwortlich für die Korrespondenz mit Ihren Entwicklerteams
- Bereitstellung eines Zugangs zu einer auf Ihren Anwendungsfall zugeschnittenen Entwicklerumgebung
- Kickoff mit einem ioki Entwickler für die Übermittlung wertvoller technischer Details
- Während der heißen Phase der Integration unterstützen wir Ihr Entwicklungsteam mit einem wöchentlichen Video-Check-In durch einen Senior-Entwickler: Wir haben die Erfahrung gemacht, dass ein regelmäßiger Austausch den Entwicklungsprozess massiv beschleunigt
API Guide
Die ioki APIs haben gemeinsame Gestaltungsprinzipien. Beispiele dafür sind: Welche Header werden benötigt, wie funktioniert die Paginierung, wie macht die API Fehler sichtbar und viele weitere Themen. Teile dieser Dokumentation können für die meisten, aber nicht unbedingt für alle APIs, Endpunkte und Anwendungsfälle relevant sein.
Passenger API
Die Passenger API ist die Schnittstelle, die die Entwicklung von vollwertigen DRT Fahrgast Clients in allen Varianten ermöglicht. Die meisten grundlegenden Clients bestehen aus einer recht einfachen Benutzeroberfläche, auf der ein Benutzer eine Fahrt von A nach B anfragen kann, ein einfaches Ergebnis erhält und dieses buchen oder ablehnen kann. Die API bietet aber noch viel mehr: Sofortige oder zukünftige Buchungen in unterschiedlichen geografischen Gebieten, Informationen zum Service vor der Fahrt, Bewertung, Bezahlung, Trinkgeld, Anzeige der Position des herannahenden Fahrzeugs, Stationsdetails, Fußgängerinformationen, Live-Updates und Zeitberechnungen, vergangene und zukünftige Fahrten, Quittungen und vieles mehr. Sie können alle von uns entworfenen Funktionen integrieren.
Driver API
Diese API stellt alle Elemente zur Verfügung, um einen Fahrer-Client zu programmieren. Dies könnte eine simple Anwendung sein, die den Fahrern Adressaten und Zeiten auflistet. Allerdings ist auch hier mehr möglich: Wir nutzen unsere eigenen APIs und stellen einen Referenz-Client mit einem vollwertigen Abbiege-Navigationssystem und einer Check-in-/Check-out-Funktionalität für Fahrgäste zur Verfügung, die den Fahrer vom Verlassen des Depots bis zu ihrer Rückkehr begleitet.
Platform API
Während die Passenger- und Driver-APIs von Clients genutzt werden, die auf mobilen Geräten laufen, ist die Platform API unsere Schnittstelle für die vollständige Integration mit fremden Backends. Mit unserem Standardprodukt streben wir Funktionsgleichheit an, und es gibt fast keine Funktion, die nicht über diese Schnittstelle gesteuert werden kann. Sie können alle Arten von Ressourcen erstellen, ändern oder löschen, z. B. neue Stationen anlegen, Ihren Fuhrpark neu konfigurieren, Schichten einrichten und die Einsatzdatenbanken synchronisieren. Unsere DRT-Plattform ist so konzipiert, dass sie sich in alle Arten von Datenflüssen und Anwendungsfällen integrieren lässt. Es ist möglich, mehrere Produkte mit mehreren Kunden zu betreiben und sogar Benutzerdatenbanken mit verschiedenen Integrationspartnern zu teilen. Für spezielle Anwendungsfälle erlaubt die Platform API sogar die Ausgabe von Zugriffstoken für die Driver- und Passenger-APIs, falls Ihr Backend im Namen bestimmter Fahrgäste oder Fahrer agieren muss.
Webhooks
Webhooks sind eine gängige Methode, um über Ereignisse innerhalb eines Systems informiert zu werden. Unsere Webhooks ermöglichen es Ihnen, über Zustandsänderungen auf dem Laufenden zu bleiben und erleichtern so einfache Anwendungsfälle wie das Auslesen einzelner Daten und komplexe wie das Auslösen von Logik auf Ihrer Seite, die dann wiederum die anderen APIs nutzen kann. Webhooks können manuell, aber auch programmgesteuert über die Platform API eingerichtet werden. Sie können immer dann ausgelöst werden, wenn etwas passiert oder auf bestimmte Ereignisse beschränkt werden. Sie sind durch eine Signatur mit einem gemeinsamen Geheimcode gesichert. Nicht zugestellte Webhooks werden mit einem exponentiellen Backoff-Algorithmus wiederholt. Der erneute Abruf von verpassten Daten über die Platform API ist auch möglich. Der Webhook-Payload enthält keine unendlich verschachtelten Datenstrukturen (die Platform API kann bei Bedarf zum Abrufen zusätzlicher Daten verwendet werden), aber dennoch: Wir senden eine vollwertige serielle Darstellung des mit dem Ereignis verbundenen Objekts mit. Die enthaltenen Daten sind also für die meisten Anwendungsfälle ausreichend.
Lassen Sie sich jetzt von unseren Expertinnen und Experten beraten!
Gestalten Sie jetzt gemeinsam mit uns die Zukunft der Mobilität Ihres bestehenden Verkehrs oder entwickeln Sie zusammen mit unseren Profis neue Ideen. Wir freuen uns über Ihre Nachricht.
