RESTful Webservice
Die billomat[API] ist als sogenannter RESTful Webservice angelegt, bei dem jede Ressource über eine eindeutige URI angesprochen wird
Welche Opertationen mit den Ressourcen durchgeführt werden, wird mittels der HTTP-Verben angegeben:
- GET: Ressourcen lesen
- POST: Ressourcen erstellen
- PUT: Ressourcen bearbeiten
- DELETE: Ressourcen löschen
Allgemeine Service-URL
[http|https]://{billomatID}.billomat.net/api/{ressource}[/{id}][/{methode}]
Parameter | Bedeutung |
|---|---|
{billomatID} | Die billomatID des Accounts |
{ressource} | Die Ressource, auf die zugegriffen werden soll |
{id} | ID der konkreten Ressource |
{methode} | Methode der allgemeinen oder konkreten Ressource |
Datenformate
Billomat versteht für schreibende Requests die Formate XML und JSON. Folgede Punkte sollten dabei beachtet werden:
- Alle Requests sollten UTF-8-kodiert sein
- Boolsche Werte sind entweder 1 (true) oder 0 (false)
- Je nach gewünschtem Format bei den schreibenden Requests muss der entsprechende Content-Type im HTTP-Header gesetzt werden ("application/xml" oder "application/json")
Responses können generell sowohl im XML-, als auch im JSON-Format erfolgen. Für spezielle Ressourcen sind auch weitere Formate mögliche (z.B. PDF).
Welches Format man als Response auf einen Request bekommen möchte, legt man über den GET-Parameter "format" fest (Standard-Format ist XML):
?format=[xml|json]
Authentifizierung
Die Authentifizierung geschieht über bestehende Billomat-Benutzer.
Ein Benutzer, der auf die billomat[API] zugreifen möchte, muss den API-Zugriff in seinen Einstellungen (unter Einstellungen > Mitarbeiter) freischalten. Anschließend muss ein persönlicher API-Schlüssel generiert werden.
Dieser API-Schlüssel ist das "Passwort" für die Benutzung der API.
API-Zugriffe sind zustandslos, d.h. dass keine Sitzungen gespeichert werden und bei jedem Request der API-Schlüssel mit übermittelt werden muss.
Der API-Schlüssel kann auf 2 unterschiedliche Arten übermittelt werden:
per GET-Parameter
curl https://{billomatid}.billomat.net/api/clients?api_key={apischluessel}
per HTTP-Header
curl -H 'X-BillomatApiKey: {apischluessel}' \
https://{billomatid}.billomat.net/api/clients
Sicherheit
Ob der Zugriff auf die API über eine verschlüsselte SSL-Verbindung (https) erfolgen kann, hängt davon ab, ob der gewünschte Account einen Tarif mit SSL-Unterstützung gebucht hat.
Generell wird empfohlen, ausschließlich über eine verschlüsselte Verbindung zu arbeiten, da die Daten ansonsten im Klartext übertragen werden und potentiell mitgelesen werden können.
Tools
Für das Lesen von Daten per GET ist ein normaler Browser ausreichend. Mit Firefox werden die XML-Daten auch übersichtlich als Baumstruktur dargestellt.
Einfach die URL der gewünschten Ressource (inkl. dem API-Schlüssel) in die Adresszeile des Browsers eingeben.
Für das Testen der restlichen Methoden (POST, PUT, DELETE) empfehlen wir entweder das Kommandozeilen-Tool curl oder als grafische Alternative das Firefox-Plugin RESTClient.
Zur besseren Veranschaulichung haben wir die Beispiele auf dieser Seite mit dem Kommandozeilen-Tool curl skizziert.
Bei den konkreten Ressourcen-Beschreibungen haben wir auf unnötigen Ballast verzichtet und nur die wichtigsten Bestandteile der Requests aufgeführt.
Daten lesen
Daten werden immer mit der HTTP-Methode GET entweder in Listen oder als Einzel-Ressource gelesen.
Eine Liste wird über den Ressourcen-Pfad gelesen:
curl -H 'X-BillomatApiKey: {apischluessel}' \
https://{billomatid}.billomat.net/api/clients
Beim Lesen einer Einzel-Ressource setzt sich die URL aus dem Ressourcen-Pfad und der ID der Ressource zusammen:
curl -H 'X-BillomatApiKey: {apischluessel}' \
https://{billomatid}.billomat.net/api/clients/1
Wenn der Request erfolgreich war, kommt der Status 200 OK und die angeforderten Daten im gewünschten Format zurück.
Die Anzahl der Datensätze per Request (bei einer Ressourcen-Liste) kann über den Parameter per_page angegeben werden, durch die einzelnen Seiten kann mit dem Parameter page navigiert werden:
curl -H 'X-BillomatApiKey: {apischluessel}' \
https://{billomatid}.billomat.net/api/clients?per_page=50&page=2
liefert 50 Kunden pro Seite und zeigt die 2. Seite (also Datensätze von 51 - 100) an.
Das XML-Root-Element einer Listen-Ressource liefert zur besseren Orientierung außerdem die 3 Attribute page (aktuelle Seite), per_page (Einträge pro Seite) und total (Gesamtanzahl über alle Seiten) zurück.
Standard-Wert für page ist 1 und für per_page ist 100, maximal können 1000 Einträge pro Seite zurückgegeben werden.
Daten schreiben
Daten werden mittels der HTTP-Methoden POST, PUT und DELETE geschrieben.
Genau wie bei der Ausgabe wir dabei standardmäßig das XML-Format verwendet. Jeder schreibende Request sollte daher im Header "Content-type: application/xml" mitsenden und die eigentlichen Daten fein säuberlich in XML-Tags verpackt im Body enthalten:
curl -v -X POST \
-H 'X-BillomatApiKey: {apischluessel}' \
-H 'Content-Type: application/xml' \
-d '<client><name>Musterfirma</name></client>' \
https://{billomatid}.billomat.net/api/clients
Alternativ kann anstatt XML auch JSON verwendet werden, wenn "Content-Type: application/json" mitgesendet wird:
curl -v -X POST \
-H 'X-BillomatApiKey: {apischluessel}' \
-H 'Content-Type: application/json' \
-d '{"client":{"name":"Musterfirma"}}' \
https://{billomatid}.billomat.net/api/clients
Dies erzeugt mittels POST eine neue Ressource - in diesem Beispie einen neuen Kunden mit der Bezeichnung 'Musterfirma'.
Als Antwort kommt der Status 201 Created und im Request-Body das komplette Objekt.
Eine bereits angelegte Ressource wird mit der PUT-Methode bearbeitet:
curl -v -X PUT \
-H 'X-BillomatApiKey: {apischluessel}' \
-H 'Content-Type: application/xml' \
-d '<client><name>Musterkunde</name></client>' \
https://{billomatid}.billomat.net/api/clients/1
War die Bearbeitung erfolgreich, kommt Status 200 OK zurück.
Das Löschen funktioniert ganz ähnlich über die DELETE-Methode, allerdings ohne zusätzliche Parameter im Request-Body:
curl -v -X DELETE \
-H 'X-BillomatApiKey: {apischluessel}' \
https://{billomatid}.billomat.net/api/clients/1
Auch hier kommt nach erfolgreichem Löschen der Status 200 OK zurück.
Fehler
Tritt ein Fehler beim Bearbeiten eines Requests auf, soll immer ein Status-Code im 400er oder 500er-Bereich zurückgeliefert werden. Meist lässt sich daraus bereits die Fehlerursache ablesen. Zusätzlich aber am besten noch eine kurze Klartext-Fehlermeldung im Response-Body:
Response: 404 Not Found<?xml version="1.0" encoding="UTF-8"?> <errors> <error>Ressource not found</error> </errors>