API Technische Details

Antwort-Codes

Sollte eine Anfrage an die API nicht korrekt beantwortet werden, wird ein Antwort-Code zurückgeliefert. Dieser setzt sich aus zwei Zahlen zusammen, die mit einem Bindestrich getrennt sind. Der AntwortCode sowie zusätzliche Informationen werden im 'ApiResponseModel' übertragen.

ApiResponse anzeigen

[ModulCode]:[ErrorCode]

Die Modulcodes und Errorcodes werden wie folgt definiert:

Sonderzeichen

Sonderzeichen in dem URL Pfad werden von der API decodiert.

Die Encodierung der Sonderzeichen erfolgt nicht.

Das bedeutet, dass zum Beispiel für die folgenden Route der, zwischen den Ziffern befindliche, Slash '/' nicht encodiert wird.

https://Controller/Action/123/456

Dies löst unter anderem eine Exception aus, weil der Slash '/' als Teil des Pfades interpretiert wird.

Für den QueryString erfolgt bereits die Encodierung.
Ein QueryString ist der Abschnitt einer URL hinter dem Fragezeichen '?'.
Mit diesem QueryString kann die Suche, z.B. nach Artikeln, eingeschränkt werden.

Im folgenden QueryString wird der Slash '/' mit %2F encodiert.
GET /Articles/Stock?searchTerm=123/456

Dieser QueryString wird zu:
GET /Articles/Stock?searchTerm=123%2F456

Damit auch der URL Pfad encodiert wird, muss dies manuell erfolgen.
Dazu werden in der SelectLine API sämtliche Parameter, die direkt in der URL angegeben werden können, decodiert.

Die Encodierung macht aus '123/456' den Wert '123~2F456'. Die Decodierung wandelt diesen Wert wieder zurück.

Im Gegensatz zu dem erwähnten QueryString werden die Parameter hierfür nicht mit dem Prozentzeichen encodiert, sondern mit der Tilde '~'.

Der Grund dafür ist, dass man in der Route der HTTP Anfrage kein Prozent angeben darf.

Im folgenden Pfad einer URL wird der Slash '/' mit ~2F encodiert.
GET /Articles/123/456

Dieser Pfad wird zu:
GET /Articles/123~2F456

Um ein nicht erlaubtes Zeichen für die SelectLine API korrekt zu encodieren, müssen folgende Schritte abgearbeitet werden:

1. Der hexadezimale Wert des nicht erlaubten Zeichens muss aus der ASCII Tabelle ermittelt werden.
   Zum Beispiel: Der hexadezimale Wert für Slash '/' ist 2F
2. Dem ermittelten hexadezimalen Wert die Tilde '~' voranstellen.
   Zum Beispiel: ~2F
3. Das nicht erlaubte Zeichen durch die gebildete neue Zeichenkette ersetzen.
   Zum Beispiel: 123~2F456

Die Tilde '~' darf daher nicht als Zeichen in Datensatzschlüsseln verwendet werden, wenn die Datensatzschlüssel über die API zum Einsatz kommen sollen.
Zu beachten ist, dass andere Sonderzeichen wie z.B. Prozent '%' ohne Encodierung und Decodierung ein ungewünschtes Verhalten auslösen. Diese Sonderzeichen könnten z.B. als Teil der URL eingestuft werden.

API Makros

Wie verwendet man API Makros?

Über die SelectLine API ist es möglich, hinterlegte Makros aufzurufen und auszuführen. Innerhalb dieser Makros können SQL-Statements definiert werden, wie sie aus dem Makro-Assistenten des SelectLine Auftrags bekannt sind. Das bedeutet, dass die üblichen SQL-Befehle, wie SELECT, UPDATE, INSERT, DELETE oder JOINs verwendet werden können. Zusätzlich können die Statements bei Bedarf auch Parameter enthalten.

Der Aufruf der Makros über die SelectLine API unterliegt keiner Berechtigungsprüfung. Das bedeutet, Makros mit Änderungs- oder Löschaufrufen werden ungehindert ausgeführt. Die Überprüfung von Berechtigungen erfolgt nur bei den durch die SelectLine API bereitgestellten Betriebsmittel, wie Artikel, Kunde usw.

Anlegen eines Makros in der Datenbank

Zum Anlegen eines Makros muss das SQL-Statement unter einem Namen mit Hilfe eines Datenbank Management Tool (z.B. das Microsoft SQL Server Management Studio) in die Tabelle APIMACRO in der Mandantendatenbank eingepflegt werden.

Name:
SelectArticleByExplicitNumber

Text:
SELECT * FROM [ART] where [Artikelnummer] = :Artikelnummer

Aufrufen eines Makros über die SelectLine API

Der Aufruf eines Makros erfolgt über den Aufruf der Ressource „Macros“ und der Angabe des Makronamens. Bei Bedarf können die Werte für vorhandene Parameter im Body übergeben werden.

Url:
POST http://localhost/Macros/SelectArticleByExplicitNumber

Header:
AUTHORIZATION: LoginId 12345-12345-12345-12345-12345

Body:
[{ 'Name': 'Artikelnummer', 'Value': '100001' }]

Das Ergebnis einer Makroausführung ist zum einen eine Liste mit den Namen der Tabellenspalten und zum anderen eine Liste sämtlicher Werte der Abfrage.

API Filter Language

Beschreibung API Filter Language

Um nach Eigenschaften der Modelle zu filtern, kann eine Kombination aus logischen und relationalen Operatoren genutzt werden. Die Abgrenzung zwischen den logischen Operatoren wird darüber hinaus durch Klammern erreicht.

Folgender Eintrag filtert beim Kunden entweder nach 'Hans Wurst' oder nach 'Peter Wurst'

http://domain:port/api/Customers?filter=(FirstName EQ 'Hans' OR FirstName EQ 'Peter') AND LastName EQ 'Wurst'

Beispiele

Alle Kunden die nach dem 1.5.2014 vom Benutzer mit Kürzel 'ap' erstellt wurden.
http://domain:port/api/Customers?filter=MetaData.CreationDate GT '20140501' AND MetaData.CreationUserToken EQ 'ap'

Alle inaktiven Kunden die in Hamburg oder Berlin wohnen.
http://domain:port/api/Customers?filter=(Address.City EQ 'Hamburg' OR Address.City EQ 'Berlin') AND Inactive EQ 1

Alle Artikel deren Gewicht grösser 5 und kleiner 10 ist
http://domain:port/api/Article?filter=Weight GT 5 AND Weight LT 10