Was eine API bereitstellt
Eine API ist eine festgelegte Möglichkeit, Funktionen oder Daten einer Software aus einer anderen Software heraus zu nutzen. Die Abkürzung steht für Application Programming Interface. Über eine solche Schnittstelle kann ein Programm beispielsweise einen Auftrag anlegen, einen Bearbeitungsstatus abrufen oder Kundendaten aktualisieren.
Bei Unternehmensanwendungen sind häufig Web-APIs gemeint. Eine Anwendung schickt eine Anfrage an eine bestimmte Adresse und erhält eine Antwort. Die Dokumentation legt fest, welche Aktionen erlaubt sind, welche Angaben benötigt werden und wie das Ergebnis aufgebaut ist. Die internen Datenbanken und Programmabläufe müssen dafür nicht offengelegt werden.
Eine Schnittstelle verbindet zwei Programme noch nicht von selbst. Jemand muss festlegen, wann welche Daten übertragen werden, wie die Felder zusammenpassen und was bei einem Fehler geschieht. Diese Umsetzung ist die Integration.
Vom Kontaktformular zum internen Vorgang
Nehmen wir ein Kontaktformular, das eine Anfrage an eine interne Aufgabenverwaltung übergeben soll. Der Besucher trägt Name, E-Mail-Adresse und Nachricht ein. Der Server der Website prüft die Eingaben und sendet die benötigten Angaben an die Schnittstelle. Das interne System legt einen Vorgang an und liefert eine Kennung zurück.
Die Integration speichert diese Kennung, damit sich die Anfrage später wieder zuordnen lässt. Sie kann außerdem festlegen, welches Team den Vorgang erhält. Dazu muss beispielsweise der Wert eines Themenfelds zu einer im Zielsystem vorhandenen Kategorie passen. Freier Text und eine interne Kategorienummer sind nicht austauschbar.
Klären Sie auch die Rückmeldung an den Besucher. Eine erfolgreich gespeicherte Formularanfrage und ein erfolgreich angelegter interner Vorgang sind zwei verschiedene Zustände. Falls die Aufgabenverwaltung ausfällt, kann die Website die Anfrage zunächst zur späteren Übertragung vormerken. Sie sollte dann nicht behaupten, dass alle nachfolgenden Schritte bereits erledigt seien.
HTTP, JSON und Webhooks einordnen
Viele Web-APIs verwenden HTTP. Die Methode GET dient dem Abruf einer Ressource; POST wird häufig verwendet, um Daten zu übermitteln und Vorgänge anzulegen. Zusätzlich zur eigentlichen Antwort erhält die aufrufende Anwendung einen Statuscode. Ob eine Anfrage angenommen wurde oder Angaben fehlen, lässt sich damit technisch unterscheiden. Die genaue fachliche Bedeutung beschreibt die jeweilige API-Dokumentation.
JSON ist ein häufig verwendetes Datenformat. Es ordnet Werten benannte Felder zu, beispielsweise einer Anfrage eine E-Mail-Adresse und eine Nachricht. Das Format allein legt noch nicht fest, ob ein Feld fehlen darf oder welche Schreibweise ein Datum haben muss. Diese Regeln gehören ebenfalls zur Schnittstellenbeschreibung.
Bei regelmäßigen Abfragen fragt Ihre Anwendung wiederholt nach Änderungen. Ein Webhook dreht die Richtung um: Das andere System benachrichtigt eine vereinbarte Adresse, wenn ein bestimmtes Ereignis eintritt. Ob das verfügbar und für Ihren Ablauf geeignet ist, hängt vom Anbieter ab. Auch Webhook-Nachrichten müssen geprüft und möglichen Vorgängen eindeutig zugeordnet werden.
Für jede Information ein führendes System festlegen
Wenn zwei Anwendungen dieselben Daten speichern, müssen Sie entscheiden, welche Fassung maßgeblich ist. Wird eine Kundenadresse im Verwaltungssystem gepflegt, sollte die Website sie nicht bei der nächsten Übertragung mit einem alten Stand überschreiben. Regeln Sie daher für jedes gemeinsam genutzte Feld, wer Änderungen auslösen darf.
Verwenden Sie stabile Kennungen für die Zuordnung. Ein Name kann mehrfach vorkommen, eine E-Mail-Adresse kann sich ändern. Eine dokumentierte Verbindung zwischen der Kennung im Quellsystem und der Kennung im Zielsystem hilft, Aktualisierungen vom Anlegen neuer Datensätze zu unterscheiden.
Legen Sie fest, was bei Löschungen, zusammengeführten Datensätzen und widersprüchlichen Änderungen passiert. Für seltene Konflikte kann eine manuelle Prüfung sinnvoller sein als eine Regel, die unbemerkt den falschen Stand übernimmt.
Fehler und doppelte Übertragungen behandeln
Ein Timeout bedeutet, dass eine Antwort nicht rechtzeitig angekommen ist. Der Auftrag könnte im Zielsystem trotzdem bereits angelegt sein. Eine erneute Anfrage kann dann einen zweiten Auftrag erzeugen. Die Integration braucht deshalb einen Weg, einen bereits verarbeiteten Vorgang zu erkennen, etwa über eine eindeutige Vorgangskennung und eine entsprechende Unterstützung im Zielsystem.
HTTP unterscheidet Methoden danach, ob Wiederholungen dieselbe beabsichtigte Wirkung haben. POST ist nicht grundsätzlich idempotent, also wiederholungssicher. Ein blindes Wiederholen ist deshalb keine allgemeine Lösung. Die Schnittstellendokumentation muss klären, welche Aktionen erneut gesendet werden dürfen.
Unterscheiden Sie vorübergehende Ausfälle von fachlichen Fehlern. Ein kurzzeitig nicht erreichbarer Dienst kann später wieder antworten. Ein fehlendes Pflichtfeld bleibt auch beim nächsten Versuch falsch. Für solche Fälle braucht eine zuständige Person eine verständliche Meldung mit Bezug zum Vorgang. Protokollieren Sie die erforderlichen Kennungen und Fehler, aber keine Zugangsschlüssel oder unnötigen vertraulichen Inhalte.
Diese Unterlagen braucht ein Schnittstellenprojekt
Beginnen Sie mit den beteiligten Systemen, der Richtung des Datenaustauschs und einem vollständigen Beispielvorgang. Ergänzen Sie die API-Dokumentation, verfügbare Testzugänge und die Ansprechpartner der Anbieter. Prüfen Sie früh, ob der gebuchte Tarif die benötigten Funktionen freischaltet.
Zugänge sollten nur die tatsächlich benötigten Aktionen erlauben. Klären Sie, wo Schlüssel gespeichert, wie sie ersetzt und wer sie bei einer Übergabe verwaltet. API-Schlüssel mit vertraulichen Berechtigungen gehören nicht in öffentlich ausgelieferten Website-Code.
Zum ersten Test gehören ein erfolgreicher Durchlauf, fehlende Daten, ein wiederholter Vorgang und ein Ausfall des Zielsystems. Vereinbaren Sie auch, wer später Fehlermeldungen bearbeitet und Änderungen an der Schnittstelle verfolgt. Damit ist neben der ersten Übertragung auch die Betreuung geklärt.
Ein Beispiel aus unserer Arbeit: Wissensdatenbank mit Produktfiltern und OAuth-Anbindung.
