Grundlagen der REST-API
Wie externe Systeme auf die Daten des Systems zugreifen: API-Schlüssel, Aufbau von Anfrage und Antwort, Fehlercodes und die interaktive API-Dokumentation.
Die REST-API des Systems gibt externen Programmen (etwa einer Buchhaltungssoftware oder einer eigenen Weboberfläche) Zugriff auf Partner-, Adress- und Bankkontodaten sowie auf die Abonnementbestellung. Jeder Aufruf erfolgt mit einem persönlichen API-Schlüssel und läuft mit den Rechten seines Inhabers.
Der erste Aufruf
- Beantragen Sie einen API-Schlüssel für Ihren Benutzer. Schlüssel werden in den Benutzereinstellungen verwaltet (Benutzer → API-Schlüssel) und können dort auch widerrufen werden.
- Bitten Sie den Administrator, Ihrem Benutzer die Funktionsrechte und Unternehmens-Inhaltsrechte zu geben, die Sie über die API nutzen möchten. Die API erlaubt genau das, was die Oberfläche erlaubt.
- Öffnen Sie die interaktive API-Dokumentation (die Adresse erhalten Sie vom Administrator). Die Dokumentation entsteht automatisch aus den Endpunkten des Systems.
- Geben Sie auf der Dokumentationsseite den API-Schlüssel ein, wählen Sie einen Endpunkt, etwa die Partnerliste, und starten Sie einen Testaufruf.
- Prüfen Sie die Antwort: Bei Erfolg kommen die Daten, bei Fehlern eine kurze Meldung und ein maschinenlesbarer Fehlercode.
Fehlercodes
| Code | Bedeutung |
|---|---|
| 401 | fehlender oder ungültiger API-Schlüssel |
| 403 | kein Funktionsrecht, oder das Unternehmen liegt außerhalb Ihrer Inhaltsrechte |
| 404 | der gesuchte Datensatz existiert nicht |
| 409 | Konflikt, etwa wenn die zu löschende Adresse von Unternehmen verwendet wird |
| 422 | fehlerhafte oder fehlende Daten |
| 500 | unerwarteter Serverfehler |
| 503 | das System wird gerade aktualisiert; versuchen Sie es in zwei Minuten erneut |
Beispiel
Der Webshop der Muster GmbH prüft mit der Steuernummer eines neuen Kunden, ob der Partner bereits existiert. Die Antwort mit Code 200 liefert Daten, Adressen und Bankkonten des Partners; gehört der Partner zu einer Unternehmensgruppe, für die der Schlüsselinhaber keine Rechte hat, gibt es keinen Treffer.