REST-API-Integrationen – Übersicht

Kunden können Stammdaten über Datenfeeds oder über unsere REST-API-Webdienste an Emburse Enterprise liefern. Eine API kann über das Internet aufgerufen und auf einem entfernten System ausgeführt werden, das die angeforderten Dienste bereitstellt. Diese bieten Flexibilität, da sie es Ihrem Unternehmen ermöglichen, Teildaten zu übergeben, anstatt eine Feed-Datei, die alle Datenzeilen enthält, unabhängig von der Anzahl der erforderlichen Aktualisierungen.

Wenn ein Teil eines API-Aufrufs fehlschlägt, wird Ihnen zudem sofort eine Fehlermeldung zugesandt, und nur der betroffene Teil der Übertragung kann nicht ausgeführt werden – der Rest des Aufrufs wird erfolgreich abgeschlossen.

Die technischen Spezifikationen für jede API finden Sie im Implementierungs-Toolkit von Emburse Enterprise. Dieser Artikel soll Ihnen helfen zu verstehen, wie unsere REST-API-Integrationen funktionieren und wie Sie sie am besten gestalten.

REST-APIs vs. Datenfeeds

Die Wahl zwischen REST-APIs und Flatfiles für Datenintegrationen hängt von den Integrationsanforderungen Ihres Unternehmens und den Eigenschaften der ausgetauschten Daten ab, und jede Option hat ihre Vor- und Nachteile. Hier sind einige Gründe, warum Sie die Verwendung einer REST-API in Betracht ziehen sollten, anstatt einen Datenfeed zu senden:

1. Echtzeit-Datenzugriff

• REST-APIs: Bieten Echtzeitzugriff auf Daten. Sie können bei Bedarf die aktuellsten Informationen senden.
• Datenfeeds: Stellen in der Regel eine Momentaufnahme von Daten zu einem bestimmten Zeitpunkt dar. Sie müssen die Dateien neu generieren oder aktualisieren, um die neuesten Informationen zu erhalten.

2. Einfache Integration

• REST-APIs: Sind für eine einfache Integration konzipiert. Sie verwenden Standard-HTTP-Methoden und sind sprachunabhängig, wodurch sie für eine Vielzahl von Programmiersprachen zugänglich sind.
• Datenfeeds: Möglicherweise ist eine benutzerdefinierte Parsing-Logik erforderlich, und der Integrationsprozess kann komplexer sein, insbesondere wenn sich die Datenstruktur häufig ändert.

3. Skalierbarkeit

• REST-APIs: Können größere Datenmengen verarbeiten, indem inkrementelle Anfragen gesendet werden, bis alle Aktualisierungen abgeschlossen sind. Dies ist ein skalierbarer Ansatz.
• Datenfeeds: Könnten mit zunehmendem Datenvolumen unhandlich werden. Die Verwaltung großer Dateien, insbesondere in verteilten Umgebungen, kann schwierig sein.

4. Sicherheit

• REST-APIs: Bieten Authentifizierungs- und Autorisierungsmechanismen an. Sie können steuern, wer auf die Daten zugreift und welche Aktionen ausgeführt werden können.
• Datenfeeds: Möglicherweise sind zusätzliche Sicherheitsmaßnahmen wie Verschlüsselung und sichere Dateiübertragungsprotokolle erforderlich, um sensible Informationen zu schützen.

5. Versionierung und Entwicklung

• REST-APIs: Ermöglichen die Versionierung, was die Verwaltung von Änderungen in der Datenstruktur im Laufe der Zeit erleichtert, ohne bestehende Integrationen zu unterbrechen.  
• Datenfeeds: Änderungen an der Struktur können eine manuelle Koordination und Kommunikation erfordern, um die Kompatibilität mit bestehenden Systemen zu gewährleisten.

6. Datengranularität

• REST-APIs: Ermöglicht Ihnen das Senden und Empfangen bestimmter Datenelemente, wodurch eine genauere Kontrolle über die von Ihnen abgerufenen Informationen ermöglicht wird. Dies hat Vorteile, wenn es mehr als eine Datenquelle gibt.
• Datenfeeds: Enthalten häufig alle Daten, was zu unnötigem Informationsabruf und unnötiger Verarbeitung führen kann.

7. Fehlerbehandlung und -protokollierung

• REST-APIs: Bieten standardisierte Fehlerbehandlungs-, Statuscodes- und Protokollierungsmechanismen, die die Fehlerbehebung erleichtern.
• Datenfeeds: Die Fehlerbehandlung erfordert eine manuelle Überwachung, da die Fehlerprotokolle per E-Mail gesendet werden und Debugging-Probleme schwieriger zu lösen sein können.

8. Echtzeit-Benachrichtigungen

• REST-APIs: Ermöglichen Echtzeitbenachrichtigungen oder Rückrufe, sodass Ihr System während der Übertragung sofort über Probleme informiert wird.
• Datenfeeds: In der Regel müssen Sie regelmäßig nach Updates suchen, was möglicherweise nicht so rasch und effizient ist.

FAQs

Gibt es Firewalls, die auf der Emburse Enterprise-Seite geöffnet werden müssen? 

Nein.

Kann man eine Mischung aus Datenfeeds und REST-APIs verwenden?

Ja. Zum Beispiel können Personendaten über SFTP und Zuordnungsdaten über REST-API gesendet werden. Sie können jedoch nicht beide Methoden für einen einzigen Typ verwenden, wie z. B. Liste und Person.

Erste Schritte mit REST-APIs

Bevor Ihr Unternehmen mit der Nutzung von REST-APIs beginnen kann, muss ein Mitglied des Emburse Enterprise-Implementierungsteams die Ressourcen, die Sie nutzen möchten, aktivieren und Ihnen Ihren Kundencode zur Verfügung stellen. (Wenn sich Ihr Unternehmen nicht mehr in der Implementierungsphase befindet, erstellen Sie einen Fall über unser Helpdesk-Serviceportal, um diese anzufordern).

Als Nächstes muss einer der Administratoren Ihres Unternehmens einen API-Schlüssel über den Verwaltungsbildschirm der API-Schlüsselverwaltung in Emburse Enterprise generieren. Weitere Informationen finden Sie im Verwaltungsbildschirm der API-Schlüsselverwaltung.

Die Kombination aus API-Schlüssel und Kundencode ermöglicht es Ihnen, REST-API-Anfragen an Emburse Enterprise zu stellen.  

curl --location --request GET 'https://service.chromeriver.com/v4/persons/10000000' \
--header 'x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'customer-code: XXXX' \
--header 'chain-id: 550e8400-e29b-41d4-a716-446655440000'

Basis-URLs

• Produktion: service.chromeriver.com/
• QA/UAT: qa-service.chromeriver.com/

REST-API-Spezifikationen

Technische Spezifikationen für jede Emburse Enterprise-API finden Sie im Implementierungs-Toolkit .

Jede API verfügt über eine Swagger-Seite, die Ihr technisches Team verwenden kann, um die Struktur der Anfragen besser zu verstehen. Diese sollten in Verbindung mit dem Dokument Datei-Integrationsspezifikation verwendet werden, das Sie in den Vorbereitungsworkshops mit unserem Implementierungsteam erhalten haben. Ihr Ansprechpartner im Emburse Enterprise-Implementierungsteam oder der Helpdesk können auch Beispiele für cURL-Anfragen bereitstellen.

Bewährte Design-Praktiken

Die folgenden Best Practices helfen Ihnen bei der Gestaltung Ihrer API-Anfragen und der Protokollierung von Fehlern für eine effektive Fehlerbehebung.

• Best Practices für Ausgaben- und Rechnungsspezifische API finden Sie unter Best Practices für Ausgaben- und Rechnungs-API-Design.

Chain-ID

Geben Sie bei Ihren API-Anfragen an Emburse Enterprise immer eine eindeutige Chain-ID an. Wir empfehlen eine GUID (Globally Unique ID). Dies hilft dem Emburse Enterprise-Support ggf. bei der Fehlerbehebung.

--header 'chain-id: 550e8400-e29b-41d4-a716-446655440000'

Wann sollte ein Feld in eine Anfrage aufgenommen werden?

Lesen Sie das Dokument Datei-Integrationsspezifikation, um besser zu verstehen, welche Daten in bestimmte Felder für Ihr Unternehmen aufgenommen werden sollten. In den meisten Fällen wird empfohlen, dieses Feld oder Array von der Anforderung auszuschließen, wenn Sie dieses Feld oder Array nicht verwenden.  

• Wenn Sie beispielsweise an der Personen-API arbeiten und das UDF-Feld nicht verwenden, fügen Sie kein leeres Array hinzu, da dies zu einem Fehler „400 fehlerhafte Anforderung“ führt.

   "udas": [
       {
           "name": "",
           "value": ""
       },

Protokollierung/Fehlerbehandlung

Wenn Sie Daten von Emburse Enterprise-APIs senden und empfangen, ist es wichtig, sich auf Protokollierungsstrategien zu konzentrieren, die die Details dieser Interaktionen für eine effektive Fehlerbehebung und Überwachung erfassen.

Im Folgenden finden Sie einige spezifische Überlegungen zum Umgang mit Protokollen in diesem Zusammenhang.

• Anforderungs- und Antwort-Payloads: Protokollieren Sie das gesamte Anforderungs-Payload (ausgehende Daten) und das Antwort-Payload (eingehende Daten) für jede API-Interaktion. Dies ist von unschätzbarem Wert für die Diagnose von Problemen im Zusammenhang mit Datenformat, Inhalt oder unerwarteten Werten.
• HTTP-Statuscodes: Protokollieren Sie die HTTP-Statuscodes, die von der Emburse Enterprise-API zurückgegeben werden. Dies bietet einen sofortigen Einblick in den Erfolg oder Misserfolg jedes API-Aufrufs.
• Header für Anfragen und Antworten: Nehmen Sie relevante Header in Ihre Protokolle auf, insbesondere solche, die sich auf die Authentifizierung, den Inhaltstyp und alle benutzerdefinierten Header beziehen, die von der Emburse Enterprise-API benötigt werden.
• Zeitstempel und Dauer: Nehmen Sie Zeitstempel in Ihre Protokolle auf, um den zeitlichen Ablauf von API-Anfragen und -Antworten zu verfolgen. Protokollieren Sie außerdem die Dauer jedes API-Aufrufs, um Leistungsengpässe zu identifizieren.
• Protokollierungsfehler und Ausnahmen: Protokollieren Sie detaillierte Informationen über Fehler oder Ausnahmen, die bei API-Interaktionen auftreten. Fügen Sie Stacktraces und Kontextinformationen hinzu, um die Fehlersuche zu erleichtern.
• Wiederholungsmechanismus: Wenn Ihre Anwendung einen Wiederholungsmechanismus für fehlgeschlagene API-Anfragen implementiert, protokollieren Sie Details zu den Wiederholungsversuchen, einschließlich der Anzahl der Versuche und aller verwendeten Backoff-Strategien.  Stellen Sie sicher, dass der Wiederholungsversuch ein Limit hat, normalerweise 1–5. Um eine Unterbrechung Ihres API-Zugriffs zu vermeiden, aktivieren Sie nicht den kontinuierlichen Wiederholungsversuch.
• Datentransformation: Wenn Ihre Anwendung Daten vor dem Senden oder nach dem Empfang von der Emburse Enterprise-API umwandelt oder abbildet, protokollieren Sie die entsprechenden Details, damit Sie eventuelle Unstimmigkeiten besser verstehen können.
• Warnungen und Überwachung: Implementieren Sie Warnmeldungen auf der Grundlage von Protokollen, um bei kritischen Problemen benachrichtigt zu werden. Verwenden Sie Tools oder Dienste zur Protokollüberwachung, um Muster und Anomalien zu erkennen.
• Kontextuelle Informationen: Fügen Sie kontextspezifische Informationen wie den Zweck oder Kontext des API-Aufrufs hinzu, um das Verständnis der Protokolle zu erleichtern, ohne auf den Code zugreifen zu müssen.
• Integrationspunkte: Protokollieren Sie eindeutig, welche Teile Ihrer Anwendung für API-Aufrufe verantwortlich sind. Dies hilft, die Ursache von Problemen in einem verteilten System zu lokalisieren.

Durch Beachtung dieser Überlegungen können Sie eine umfassende Protokollierungsstrategie entwickeln, die eine effektive Überwachung, Fehlerbehebung und Optimierung Ihrer Interaktionen mit Emburse Enterprise APIs ermöglicht. Überprüfen und aktualisieren Sie Ihre Protokollierungsstrategie regelmäßig, wenn sich Ihre Integration weiterentwickelt.