Anmeldung und Konventionen
- Manuel Schaffner
- Maurin Jenni
Der Adapter wird wie folgt umgesetzt:
- JSON-basierte REST-Schnittstelle
- Die Schnittstelle ist komplett passiv. Das Timing der Abfragen ist dem Web-Partner frei, wobei darauf zu achten ist, dass nicht unnötige Last erzeugt wird (z.B. permanente Abfrage aller Stammdaten ohne Filter).
- Die Schnittstellendefinition kann via Swagger ausgelesen werden.
- Alle Endpunkte können nur mit einem authentifizierten Benutzer verwendet werden
- Innerhalb der Schnittstelle findet keine weitere Autorisierung statt.
Filtermöglichkeiten
Auf den Abfragen werden Filtermöglichkeiten nach OData angeboten, die nach folgender Syntax arbeiten:
| Operator | Bedeutung | Beispiel |
|---|---|---|
| eq | Gleich | city eq 'Redmond' and name eq null |
| ne | Ungleich | city ne 'London' |
| gt | Grösser | price gt 20 |
| ge | Grösser oder gleich | price ge 10 |
| lt | Kleiner | price lt 20 |
| le | Kleiner oder gleich | price le 100 |
| and | Und | price le 200 and price gt 3.5 |
| or | Oder | price le 3.5 or price gt 200 |
| not | Negation | not price le 3.5 |
| ( ) | Priorisierung | (priority eq 1 or city eq 'Redmond') and price gt 100 |
| skip, top | Paging | $top=30&$skip=220 |
Datumsformatierung
Datumangaben müssen nach ISO 8606 inkl. Zeitzone codiert werden.
Beispiel in einem OData-Filter: $filter=modifiedDate gt 2021-06-14T00:00:00Z
Belastung der Schnittstelle
Die Belastung der Schnittstelle ist wie folgt vorgesehen:
- Artikelstamm / Produktinformationen und Produzenten sollten im Web-Server gecached werden. Diese Abfragen können grosse Last und somit Zeitverlust bei der Abfrage verursachen.
- Dort wo vorhanden wird auf den Tabellen ein Timestamp der letzten Änderung angeboten. Damit können Delta-Abfragen gemacht werden, um die Daten schneller abzugleichen.
Authentifizierung
Sämtliche REST-Endpunkte erlauben den Zugriff nur mit Authentifizierung. Einzige Ausnahme ist der folgende Token-Request. Die Antwort enthält ein Bearer-Token (access_token), das beim Zugriff auf die REST-Endpunkte im Http-Header mitgegeben werden muss.
Url: /api/Identity/Realm/RequestToken
Bsp. Demo-Server: https://vinxapi.i-ag.ch/api/Identity/Realm/RequestToken
Felder
Feld | Typ | Info |
|---|---|---|
client_id | string | Konstante "Integrated" |
scope | string | Konstante "VinX.Shop" |
username | string | Benutzername |
password | string | Passwort |
Beispiel Body:
{
"client_id": "Integrated",
"scope": "VinX.Shop",
"username": "<User>",
"password": "<Pwd>"
}
Beispiel Antwort:
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijc2ODczNkI5NERFRjU1RjIxNDFBNTQ4NTJGRjM3RjlDODk3QjlBNzIiLCJ4NXQiOiJkb2MydVUzdlZmSVVHbFNGTF9OX25JbDdtbkkiLCJ0eXAiOiJKV1QifQ.eyJyb2xlIjoiQ3JlYXRlfFJlYWR8VXBkYXRlfERlbGV0ZXxFeGVjdXRlOkdlbmVyYWxAQ2FtcHVzU3Vyc2VlLlJFU1QiLCJ1bmlxdWVfbmFtZSI6IlN0dWlxIiwibmJmIjoxNTkzMDc1ODI4LCJleHAiOjE1OTMwNzc2MjgsImlhdCI6MTU5MzA3NTgyOCwiaXNzIjoiaHR0cDovL3cxMG1hcy1uZXQ6ODA4NSJ9.Q_aN6n1i0QpDbTflqafqQcLPN_Xz_Qk1FXarTLZ9T4ohhpmdL2YlH7SQR4WGKPcoJvbZeWIHBy0h4ByxB06ILKL2pFypUpWobGKfp8C4gEBgqi1xfRtvMgUPR3JUhmFTJhpijGD0lbJJ7SpPCydgyCwufyVmfgX_U308CQY40fuDtEA6xNs-wZpGGd0a0WygFf1xqmbaz3TdptqNGddl22GsJscuvkbSrrf572Ke3Hfn_bj7KXk-5FB06dkb-0tAwvnXf7PTY_Xgc1Unm04AiwRb5kL1SsfPWjH9LCdn4sJuw1pUQev1dcj9tHtQ",
"token_type": "Bearer",
"user": "<User>",
"userRole": "Create|Read|Update|Delete|Execute:General@VinX.Shop",
"userShouldChangePassword": false
}