Schnittstellen-Programmierung und APIs verständlich erklärt
In fast jedem Betrieb laufen mehrere Programme: eines für Angebote und Rechnungen, eines für Termine, vielleicht noch ein Onlineshop oder eine Branchenlösung. Damit Daten nicht von Hand übertragen werden müssen, brauchen diese Programme eine gemeinsame Sprache. Genau das ist eine Schnittstelle.
Ein Bild zum Einstieg
Stellen Sie sich eine Schnittstelle wie eine Bestelltheke vor. Sie müssen nicht wissen, wie die Küche organisiert ist. Sie müssen nur wissen, was auf der Karte steht und wie man bestellt. Die Küche liefert dann, was bestellt wurde, in einer verabredeten Form.
Bei Software ist es ähnlich. Ein Programm bietet an, bestimmte Daten herauszugeben oder entgegenzunehmen, zum Beispiel „neuen Kunden anlegen“ oder „offene Rechnungen abfragen“. Ein anderes Programm nutzt dieses Angebot, ohne die inneren Abläufe des ersten zu kennen.
Drei Arten von Schnittstellen
- Datei-AustauschEin Programm schreibt eine Datei, etwa im CSV-Format, ein anderes liest sie ein. Das ist die einfachste Form und oft schon ein großer Fortschritt gegenüber dem Abtippen. Nachteil: Jemand muss den Austausch anstoßen, und die Daten sind nur so aktuell wie die letzte Datei.
- APIAPI steht für Application Programming Interface, auf Deutsch Programmierschnittstelle. Ein Programm stellt dabei über das Internet feste Adressen bereit, über die andere Programme Daten abfragen oder übergeben. Das geschieht automatisch und in Sekunden. Die meisten modernen Dienste bieten eine solche API an.
- WebhookEin Webhook dreht die Richtung um. Statt regelmäßig nachzufragen, ob es Neues gibt, meldet sich das eine Programm von selbst beim anderen, sobald etwas passiert, etwa wenn ein Auftrag eingeht oder eine Zahlung verbucht wurde.
Welche Art in Frage kommt, hängt davon ab, was die beteiligten Programme anbieten. Nicht jedes ältere Programm hat eine API, aber fast jedes kann Daten exportieren.
Beispiele aus dem Betrieb
- Eine Anfrage über das Kontaktformular der Website legt automatisch einen Kontakt im Kundenverzeichnis an.
- Abgeschlossene Aufträge aus der Außendienst-App werden als Rechnungsentwurf an das Buchhaltungsprogramm übergeben.
- Ein neuer Termin im Kalender löst eine Erinnerung per E-Mail an den Kunden aus.
- Messwerte vernetzter Geräte erscheinen ohne Zutun in der Übersicht des Betriebs.
Den zweiten und den vierten Fall kennen wir aus eigener Arbeit: In TrapMap übergeben wir Abrechnungsdaten an Lexware und sevDesk und binden vernetzte Fallen von TrapLinked und Futura an.
Beispiele aus Handwerk und Dienstleistung
In Betrieben, die beim Kunden arbeiten, entstehen Daten an zwei Orten: draußen auf der Baustelle oder im Objekt und drinnen im Büro. Schnittstellen sorgen dafür, dass beides zusammenkommt. Drei typische Fälle zeigen, welche der drei Arten jeweils passt:
- Preise vom Großhandel (Datei-Austausch)Viele Handwerksbetriebe erhalten Artikel und Preise ihrer Großhändler als Datei, im Handwerk verbreitet ist dafür das Format Datanorm. Eine Schnittstelle liest diese Datei regelmäßig ein, damit Angebote mit aktuellen Preisen entstehen, ohne dass jemand Preislisten abgleicht.
- Material und Stunden in die Rechnung (API)Der Monteur trägt verbrauchtes Material und Arbeitszeit auf dem Handy ein. Ist der Auftrag abgeschlossen, legt eine Schnittstelle über die API des Rechnungsprogramms einen Rechnungsentwurf an. Im Büro wird nur noch geprüft und verschickt.
- Online gebuchter Termin im Einsatzplan (Webhook)Ein Dienstleister bietet Termine über ein Buchungsformular an. Sobald jemand bucht, meldet das Buchungssystem den Termin per Webhook, und er erscheint mit Anschrift und Anliegen im Einsatzplan des Teams.
Welche Abläufe in solchen Betrieben noch zusammenhängen, beschreibt die Seite Software für Handwerk und Dienstleister.
Wie die Daten aussehen
Über eine API werden Daten meist im Format JSON ausgetauscht. Das ist strukturierter Text, den Maschinen leicht lesen können und den auch Menschen noch verstehen. Ein Kunde besteht dann zum Beispiel aus Feldern wie Name, Anschrift und Kundennummer.
Die eigentliche Arbeit beim Verbinden zweier Programme liegt oft nicht in der Technik, sondern in der Zuordnung. Heißt das Feld im einen Programm „Firma“ und im anderen „Unternehmen“? Wie werden Anreden, Steuersätze oder Einheiten verschlüsselt? Was passiert mit Einträgen, die es nur in einem der beiden Programme gibt? Diese Fragen müssen fachlich beantwortet werden, bevor die erste Zeile Code entsteht.
So läuft das Programmieren einer Schnittstelle ab
Ob eine Verbindung klein oder groß ist, die Schritte sind meist dieselben:
- Zweck festlegenWelche Daten sollen in welche Richtung fließen, und was soll danach passieren? Ein Satz wie „Abgeschlossene Aufträge werden zu Rechnungsentwürfen“ genügt als Anfang.
- Zugänge prüfenDie Dokumentation der beteiligten Programme zeigt, welche Daten sich lesen und schreiben lassen. Manche Anbieter stellen dafür eine Testumgebung bereit, in der sich ohne Risiko für echte Daten arbeiten lässt.
- Felder zuordnenFür jedes Feld wird festgelegt, wohin es gehört und wie es umgewandelt wird. Sonderfälle wie Gutschriften oder Kunden ohne Kundennummer kommen hier auf den Tisch.
- Programmieren und testenErst jetzt entsteht der Code. Getestet wird mit Beispieldaten, die auch die Sonderfälle enthalten, nicht nur den Normalfall.
- Inbetriebnahme und PflegeNach dem Start zeigt ein Protokoll, was übertragen wurde. Ändert ein Anbieter seine API, wird die Verbindung angepasst.
Wer seine Abläufe dafür beschreiben möchte, findet eine Anleitung im Ratgeber Anforderungen für eine Software formulieren.
Sicherheit und Zugriff
Eine Schnittstelle öffnet ein Programm nach außen. Deshalb braucht sie einen Schlüssel: Nur wer einen gültigen Zugangsschlüssel oder ein Anmelde-Token hat, darf Daten abrufen. Diese Schlüssel gehören nicht in E-Mails oder Tabellen, sondern sicher verwahrt in die Einstellungen der verbundenen Anwendung.
Ein guter Grundsatz ist, jeder Verbindung nur die Rechte zu geben, die sie braucht. Eine Anbindung, die Rechnungsentwürfe anlegt, muss keine Bankdaten lesen können. Fließen personenbezogene Daten an einen externen Dienst, ist außerdem der Datenschutz zu prüfen.
Wenn etwas schiefgeht
Schnittstellen laufen meist unbemerkt im Hintergrund. Gerade deshalb müssen Fehler auffallen. Ein Dienst ist kurz nicht erreichbar, ein Anbieter ändert seine API, ein Datensatz hat ein unerwartetes Format: All das kommt vor.
- Fehlgeschlagene Übertragungen sollten automatisch wiederholt werden.
- Bleibt ein Fehler bestehen, sollte jemand benachrichtigt werden, statt dass Daten still verloren gehen.
- Ein Protokoll zeigt, was wann übertragen wurde, damit sich Fragen später klären lassen.
- Ankündigungen der Anbieter zu Änderungen an ihrer API sollten im Blick behalten werden.
Diese Pflege gehört zum laufenden Betrieb, siehe Wartung und Weiterentwicklung.
Fragen an Ihren Softwareanbieter
Wenn Sie zwei Programme verbinden möchten, helfen diese Fragen an die jeweiligen Anbieter weiter:
- Gibt es eine dokumentierte API, und ist sie in meinem Tarif enthalten?
- Welche Daten lassen sich lesen, welche schreiben?
- Gibt es Webhooks für die Ereignisse, die mich interessieren?
- Gibt es Grenzen, wie viele Anfragen pro Minute oder Tag erlaubt sind?
- Wo werden die Daten verarbeitet, und gibt es einen Vertrag zur Auftragsverarbeitung?
Mit den Antworten lässt sich schnell einschätzen, ob eine Anbindung einfach, aufwendig oder nur über Umwege möglich ist. Wie wir Programme verbinden, beschreibt die Seite Schnittstellen und API-Anbindung.
Checkliste: Anforderungen an eine Schnittstelle
Bevor eine Schnittstelle programmiert wird, sollten diese Punkte geklärt sein. Sie fassen zusammen, was in den Abschnitten oben steht, und sind zugleich eine gute Grundlage für ein Angebot. Offene Punkte sind kein Hindernis für ein erstes Gespräch.
- ZweckEin Satz: Welche Daten sollen in welche Richtung fließen, und was soll danach passieren?
- Beteiligte ProgrammeWelche Programme sind dabei, in welchem Tarif oder welcher Version laufen sie, und wer ist beim jeweiligen Hersteller Ansprechpartner?
- ZugängeGibt es eine dokumentierte API im eigenen Tarif? Was lässt sich lesen, was schreiben? Gibt es Webhooks, eine Testumgebung und Grenzen für die Zahl der Anfragen?
- Art der VerbindungDatei-Austausch, API oder Webhook? Hat ein Programm keine API, ist oft ein regelmäßiger Datei-Export möglich.
- Felder und SonderfälleWelches Feld gehört wohin, und wie werden Anreden, Steuersätze oder Einheiten umgewandelt? Was passiert mit Einträgen, die es nur in einem Programm gibt? Dazu einige echte Beispieldatensätze, auch mit Sonderfällen wie Gutschriften oder Kunden ohne Kundennummer.
- Sicherheit und DatenschutzWo werden die Zugangsschlüssel sicher verwahrt, und welche Rechte braucht die Verbindung wirklich? Fließen personenbezogene Daten an einen externen Dienst: Wo werden sie verarbeitet, und gibt es einen Vertrag zur Auftragsverarbeitung?
- Fehler und BetriebWerden fehlgeschlagene Übertragungen wiederholt, wer wird bei bleibenden Fehlern benachrichtigt, wo steht das Protokoll, und wer passt die Verbindung an, wenn ein Anbieter seine API ändert?
Ordnen Sie die Punkte danach in Muss, Soll und Kann. Wie das geht, zeigt der Ratgeber Anforderungen für eine Software formulieren.
Häufige Fragen
Mein Programm hat keine API. Lässt es sich trotzdem anbinden?
Oft ja, zum Beispiel über einen regelmäßigen Datei-Export oder eine Datenbank, auf die man lesend zugreifen kann. Das ist weniger elegant als eine API, löst aber häufig schon das Problem des Abtippens.
Ist eine Schnittstelle dasselbe wie eine Automatisierung?
Nicht ganz. Die Schnittstelle ist der Weg, auf dem Daten fließen. Eine Automatisierung legt fest, wann und unter welchen Bedingungen sie fließen und was danach passiert. Beides gehört meist zusammen.
Muss eine Schnittstelle immer programmiert werden?
Nein. Viele Programme bringen fertige Verbindungen zu verbreiteten Diensten mit, die sich in den Einstellungen einschalten lassen. Programmiert wird, wenn es keine fertige Verbindung gibt, wenn Felder anders zugeordnet werden müssen, als die fertige Lösung es vorsieht, oder wenn die Daten nicht über einen weiteren Dienst laufen sollen.
Was sollte ich vorbereiten, bevor ich eine Schnittstelle programmieren lasse?
Notieren Sie, welche Programme beteiligt sind und in welchem Tarif oder welcher Version sie laufen, welche Daten fließen sollen und wer beim jeweiligen Hersteller Ansprechpartner ist. Ein paar echte Beispieldatensätze, auch mit Sonderfällen, helfen bei der Einschätzung sehr.
Welche Anforderungen sollte ich an eine Schnittstelle stellen?
Legen Sie fest, welche Daten in welche Richtung fließen sollen, welche Programme beteiligt sind, wie Felder zugeordnet werden und wie Fehler auffallen. Die Checkliste oben fasst die Punkte zusammen.
Sie möchten Programme verbinden?
Beschreiben Sie kurz, worum es geht. Wir melden uns mit Rückfragen oder einem Vorschlag für ein erstes Gespräch.
Kontaktformular