Grundlagen

Kostenlos testen

REST­ful Webservice

Die billomat[API] ist als soge­nann­ter REST­ful Web­ser­vice ange­legt, bei dem jede Res­source über eine ein­deu­tige URI ange­spro­chen wird.
Wel­che Operta­tio­nen mit den Res­sour­cen durch­ge­führt wer­den, wird mit­tels der HTTP-Verben angegeben:

  • GET: Res­sour­cen lesen
  • POST: Res­sour­cen erstellen
  • PUT: Res­sour­cen bearbeiten
  • DELETE: Res­sour­cen löschen

All­ge­meine Service-URL

[http|https]://{billomatID}.billomat.net/api/{ressource}[/{id}][/{methode}]
Para­me­ter Bedeu­tung
{bil­lo­ma­tID} Die bil­lo­ma­tID des Accounts
{res­source} Die Res­source, auf die zuge­grif­fen wer­den soll
{id} ID der kon­kre­ten Ressource
{methode} Methode der all­ge­mei­nen oder kon­kre­ten Ressource

Daten­for­mate

Bil­lo­mat ver­steht für schrei­bende Requests die For­mate XML und JSON. Fol­gende Punkte soll­ten dabei beach­tet werden:

  • Alle Requests soll­ten UTF-8-kodiert sein
  • Bool­sche Werte sind ent­we­der 1 (true) oder 0 (false)
  • Je nach gewünsch­tem For­mat bei den schrei­ben­den Requests muss der ent­spre­chende Content-Type im HTTP-Header gesetzt wer­den (“application/xml” oder “application/json”)

Respon­ses kön­nen gene­rell sowohl im XML-, als auch im JSON-Format erfol­gen. Für spe­zi­elle Res­sour­cen sind auch wei­tere For­mate mög­li­che (z.B. PDF).
Wel­ches For­mat man als Response auf einen Request bekom­men möchte, legt man über den GET-Parameter “for­mat” fest (Standard-Format ist XML):

?format=[ xml | json ]

Alter­na­tiv kann das For­mat auch über einen HTTP-Header bestimmt werden:

Accept: application/json

Authen­ti­fi­zie­rung

Die Authen­ti­fi­zie­rung geschieht über beste­hende Billomat-Benutzer.
Ein Benut­zer, der auf die billomat[API] zugrei­fen möchte, muss den API-Zugriff in sei­nen Ein­stel­lun­gen (unter Ein­stel­lun­gen > Mit­ar­bei­ter) frei­schal­ten. Anschlie­ßend muss ein per­sön­li­cher API-Schlüssel gene­riert wer­den.
Die­ser API-Schlüssel ist das “Pass­wort” für die Benut­zung der API.
API-Zugriffe sind zustands­los, d.h. dass keine Sit­zun­gen gespei­chert wer­den und bei jedem Request der API-Schlüssel mit über­mit­telt wer­den muss.
Der API-Schlüssel kann auf 2 unter­schied­li­che Arten über­mit­telt 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

Sicher­heit

Der Zugriff auf die API kann unab­hän­gig vom gebuch­ten Tarif wahl­weise ver­schlüs­selt über https oder unver­schlüs­selt über http erfol­gen.
Gene­rell wird emp­foh­len, aus­schließ­lich über eine ver­schlüs­selte Ver­bin­dung zu arbei­ten, da die Daten ansons­ten im Klar­text über­tra­gen wer­den und poten­ti­ell mit­ge­le­sen wer­den können.

Tools

Für das Lesen von Daten per GET ist ein nor­ma­ler Brow­ser aus­rei­chend. Mit Fire­fox wer­den die XML-Daten auch über­sicht­lich als Baum­struk­tur dar­ge­stellt.
Ein­fach die URL der gewünsch­ten Res­source (inkl. dem API-Schlüssel) in die Adress­zeile des Brow­sers ein­ge­ben.
Für das Tes­ten der rest­li­chen Metho­den (POST, PUT, DELETE) emp­feh­len wir ent­we­der das Kommandozeilen-Tool curl oder als gra­fi­sche Alter­na­tive das Firefox-Plugin REST­Cli­ent.

Zur bes­se­ren Ver­an­schau­li­chung haben wir die Bei­spiele auf die­ser Seite mit dem Kommandozeilen-Tool curl skizziert.

Bei den kon­kre­ten Ressourcen-Beschreibungen haben wir auf unnö­ti­gen Bal­last ver­zich­tet und nur die wich­tigs­ten Bestand­teile der Requests aufgeführt.

Daten lesen

Daten wer­den immer mit der HTTP-Methode GET ent­we­der in Lis­ten oder als Einzel-Ressource gele­sen.
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 Res­source zusammen:

curl -H 'X-BillomatApiKey: {apischluessel}' \

https://{billomatid}.billomat.net/api/clients/1

Wenn der Request erfolg­reich war, kommt der Sta­tus 200 OK und die ange­for­der­ten Daten im gewünsch­ten For­mat zurück.
Die Anzahl der Daten­sätze per Request (bei einer Ressourcen-Liste) kann über den Para­me­ter per_page ange­ge­ben wer­den, durch die ein­zel­nen Sei­ten kann mit dem Para­me­ter page navi­giert werden:

curl -H 'X-BillomatApiKey: {apischluessel}' \

https://{billomatid}.billomat.net/api/clients?per_page=50&page=2

lie­fert 50 Kun­den pro Seite und zeigt die 2. Seite (also Daten­sätze von 51 — 100) an.
Das XML-Root-Element einer Listen-Ressource lie­fert zur bes­se­ren Ori­en­tie­rung außer­dem die 3 Attri­bute page (aktu­elle Seite), per_page (Ein­träge pro Seite) und total (Gesamt­an­zahl über alle Sei­ten) zurück.
Standard-Wert für page ist 1 und für per_page ist 100, maxi­mal kön­nen 1000 Ein­träge pro Seite zurück­ge­ge­ben werden.

Daten schrei­ben

Daten wer­den mit­tels der HTTP-Methoden POST, PUT und DELETE geschrie­ben.
Genau wie bei der Aus­gabe wir dabei stan­dard­mä­ßig das XML-Format ver­wen­det. Jeder schrei­bende Request sollte daher im Hea­der “Content-type: application/xml” mit­sen­den und die eigent­li­chen Daten fein säu­ber­lich in XML-Tags ver­packt 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

Alter­na­tiv kann anstatt XML auch JSON ver­wen­det wer­den, wenn “Content-Type: application/json” mit­ge­sen­det 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 mit­tels POST eine neue Res­source — in die­sem Bei­spie einen neuen Kun­den mit der Bezeich­nung ‘Mus­ter­firma’.
Als Ant­wort kommt der Sta­tus 201 Crea­ted und im Request-Body das kom­plette Objekt.
Eine bereits ange­legte Res­source 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 Bear­bei­tung erfolg­reich, kommt Sta­tus 200 OK zurück.
Das Löschen funk­tio­niert ganz ähnlich über die DELETE-Methode, aller­dings ohne zusätz­li­che Para­me­ter im Request-Body:

curl -v -X DELETE \
-H 'X-BillomatApiKey: {apischluessel}' \

https://{billomatid}.billomat.net/api/clients/1

Auch hier kommt nach erfolg­rei­chem Löschen der Sta­tus 200 OK zurück.

Feh­ler

Tritt ein Feh­ler beim Bear­bei­ten eines Requests auf, soll immer ein Status-Code im 400er oder 500er-Bereich zurück­ge­lie­fert wer­den. Meist lässt sich dar­aus bereits die Feh­ler­ur­sa­che able­sen. Zusätz­lich aber am bes­ten noch eine kurze Klartext-Fehlermeldung im Response-Body:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>Ressource not found</error>
</errors>