Verwendung der API

Um Daten über die API zu Lesen oder zu Schreiben muss ein Http-Aufruf in einer bestimmten Form erfolgen. Die API folgt dabei den Konventionen eines REST-Dienstes, bei dem die verschiedenen Dienstangebote über entsprechende Urls und Http-Verben bereit gestellt werden. Jede Information hat eine eindeutige Url. Zum Lesen der Information muss das GET Http-Verb verwendet werden. Für das Schreiben wird entweder das POST Http-Verb (Information anlegen) oder das PUT Http-Verb (Information ändern) verwendet.

Als Format, in dem Informationen erhalten oder übermitteln werden, kommt JSON zum Einsatz. Das Antwortformat wird über den Header wie folgt übermittelt:
ACCEPT: application/json

Wenn Daten übermitteln werden, muss auch dieses Format definiert werden:
CONTENT-TYPE: application/json

Viele Funktionen benötigen eine Authentifizierung, welche durch einen Login erfolgen muss. Die LoginId, welche man durch den Login erhält, muss im Header eines Aufrufes immer mitgegeben werden:
Authorization: LoginId 12345-12345-12345-12345-12345

Login

Um sich bei der API anzumelden, muss ein Http-Aufruf mit dem Http-Verb POST erfolgen. Der Benutzername, das Passwort und der AppKey werden im Body dieses Aufrufes übertragen. Der AppKey muss in der verwendeten Lizenz hinterlegt sein. Das Format der Daten muss im Header angegeben werden:

Url:
POST http://localhost/Login
Header:
CONTENT-TYPE: application/json
Body:
{ "username":"[UserName]", "password":"[Password]", "AppKey":"[AppKey]" }
Bei richtigem Benutzernamen und Passwort erhalten Sie als Antwort die LoginId (Access-Token).
{"AccessToken":"ec2fbd7c-a184-4849-ba9f-1a35782383a9", "TokenType":"LoginId"}

Informationen lesen

Um einen Kunden abzurufen muss eine GET Http-Anfrage gesendet werden. In der Url muss die Kundennummer angegeben werden. Das Abrufen von Kunden erfordert eine Authentifizierung, daher muss im Header die LoginId angegeben werden.

Url:
GET http://localhost/Customers/12345
Header
AUTHORIZATION: LoginId 12345-12345-12345-12345-12345
ACCEPT: application/json

Informationen anlegen

Wenn ein Kunde erstellt werden soll, müssen die Daten des Kunden per POST an die entsprechende URL übertragen werden. Das Format und die Authentifizierung müssen im Header angegeben werden. Die Eigenschaften eines Kunden, die nicht übertragen werden sollen, werden von der API mit Vorgabewerten gefüllt. Die Eigenschaften, die als NurLesbar (ReadOnly) markiert sind, können nicht geschrieben werden.

Url:
POST http://localhost/Customers
Header:
AUTHORIZATION: LoginId 12345-12345-12345-12345-12345
CONTENT-TYPE: application/json
Body
{"FirstName":"John", "LastName":"Doe" }

Informationen ändern

Um einen Kunden zu ändern, muss eine eine PUT Http-Anfrage an die ensprechende URL unter Angabe der Kundennummer gesendet werden. Das Format und die Authentifizierung müssen im Header angegeben werden. Die Eigenschaften eines Kunden, die Sie nicht übertragen, werden auch nicht geändert. Die Eigenschaften, die als NurLesbar (ReadOnly) markiert sind, können nicht geändert werden.

Url:
PUT http://localhost/Customers/12345
Header:
AUTHORIZATION: LoginId 12345-12345-12345-12345-12345
CONTENT-TYPE: application/json
Body:
{"LastName":"Smith" }