API Grundlagen / Einführung

Installation

Die Details zur Installation finden Sie unter API.

Grundlegende Funktionen der REST-API und zum Login in die SelectLine API.

Wie benutzt man die 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.

Das Format, in dem Informationen erhalten oder übermitteln werden, kann gewählt werden. Aktuell sind die Formate JSON und XML möglich Das Antwortformat wird über den Header wie folgt übermittelt:

JSON:
ACCEPT: application/json

XML:
ACCEPT: application/xml

Wenn Daten übermitteln werden, muss auch dieses Format wie folgt definiert werden:

JSON:
CONTENT-TYPE: application/json

XML:
CONTENT-TYPE: application/xml

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 Aufrufs 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 und das Passwort werden im Body dieses Aufrufs übertragen. Das Format der Daten muss im Header angegeben werden

Url:
POST http://localhost/Login

Header:
CONTENT-TYPE: application/json

Body:
{ "username":"[UserName]", "password":"[Password]" }

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/xml

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 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" }

Swagger

Swagger bietet vorgenerierten Code zum Zugriff auf die SelectLine API in diversen Programmiersprachen. Zusätzlich kann man eigene Anfragen direkt gegen die Installation der SelectLine API testen.

Was ist Swagger?

Swagger-Dokumentation und Testumgebung

Swagger-Api-Download (Swagger ist Open Source Software und unter der Apache License Version 2.0 lizenziert)

Codegenerierung mit Swagger-Codegen

Zum Ausführen der Codegenerierung werden folgende Programme benötigt:

• Java JRE
• Swagger-CodeGen

Hinweis: auf der Internetseite den grossen Download-Button drücken.

Auf der Hilfe-Seite von SelectLine API ist die Swagger-API-Beschreibungsdatei herunterzuladen.

In der Kommandozeile (Windows) kann zur Erzeugung von C#-Proxyklassen inklusive Demoprogramme und Tests folgender Befehl abgesetzt werden:

java -jar swagger-codegen-cli-2.2.1.jar generate -i SelectLine.API.json -l csharp -o c#

Weitere unterstützte Programmiersprachen und Bibliotheken sind u.a.: CsharpDotNet2, aspnet5, android, objc, dynamic-html, html, html2, php, cpprest, java, javascript, typescript, typescript-angular, typescript-angular2, ...

Code-Beispiele

Beispiele zur Nutzung der SelectLine API in C#/WPF, PowerShell, JavaScript und PHP.