Erste Schritte

Dieser Abschnitt beschreibt die Web API der Plattform, umgesetzt als REST-API-Datenpaket für den Austausch im Format json.

Allgemeine Informationen

• Datenübertragungsformat Die Web API ist als REST-API-Datenpaket für den Austausch im json-Format umgesetzt.
• Authentifizierungsverfahren Die Authentifizierung beruht auf einem dynamisch erneuerten Token, das die Sicherheit der empfangenen Daten gewährleistet und ein Abgreifen des Tokens verhindert.
• Format der Variablen mit Datum und Uhrzeit Die Web API gibt Daten vom Typ Datum und Uhrzeit in der Kodierung UNIX time bzw. POSIX time im Format UTC: 1613376963 zurück. Bei der Umrechnung von Unix time in ein lesbares Datum ist die Zeitzone anzugeben.
• Paginierung Die Web API stellt eine Paginierung für das seitenweise Laden von Daten bereit. Die Übergabe erfolgt über den Parameter: page="page number" (page=1). Die Anzahl der in der Abfrage zurückgegebenen Datensätze lässt sich über den Parameter per_page festlegen, jedoch höchstens 1000 Datensätze.

Basis-URL

Alle Beispiele auf diesen Seiten verwenden die folgende Basis-URL:

https://api.vadsro.eu/api/v1

Authentifizierung

Die Authentifizierung beruht auf einem dynamisch erneuerten Token. In der Praxis sieht das folgendermaßen aus:

• Die Erstauthentifizierung erfolgt mit einer im System vorhandenen E-Mail-Adresse und dem dazugehörigen Passwort; als Antwort werden ein dynamisches Token und die zugehörigen Attribute zurückgegeben.
• Anschließend wird die eigentliche Anfrage zum Abruf der Daten gebildet, wobei das im vorherigen Schritt erhaltene Token den Headern der HTTP-Anfrage hinzugefügt wird.
• Die Anfrage wird an den Server gesendet. Ist die Anfrage korrekt gebildet, liefert der Server die Daten im Antworttext und ein neues Token in den Antwort-Headern zurück, während das alte Token seine Gültigkeit verliert. Mit dem neuen Token lässt sich der vorherige Schritt wiederholen und so fort.
• Nach Abschluss der Arbeit kann das letzte Token vor Ablauf seiner Gültigkeitsdauer ungültig gemacht werden (SignOut).

Die Erstauthentifizierung nutzt E-Mail-Adresse und Passwort eines vorhandenen Benutzers. Dazu ist eine POST-Anfrage an folgende Adresse zu senden:

https://api.vadsro.eu/api/v1/auth/sign_in

Beispiel einer Anfrage im Curl-Format:

curl -i --header "Content-Type: application/json" \
     --request POST \
     --data '{"email":"api-user@example.com","password":"Str0ngPas$"}'\
     https://api.vadsro.eu/api/v1/auth/sign_in

Als Antwort erhalten wir die folgende Nachricht:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-1
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615227012
uid: api-user@example.com
ETag: W/"5b9bcc76f7223b72b79d9f2d31ff0fd5"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: c18e06b4-e5bd-40b5-875d-7ac958e2fbb5
X-Runtime: 0.391069
Transfer-Encoding: chunked
{"data":{"id":6,"email":"api-user@example.com","provider":"email","uid":"api-user@example.com","name":"API user"}}

In dieser Antwort interessieren uns die folgenden Header:

Beispiel einer Anfrage mit dem Token aus der vorherigen Antwort:

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-1" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request GET \
 --header "Content-Type: application/json" \
 --data '{"page":"2"}' \
 https://api.vadsro.eu/api/v1/stations

Als Antwort erhalten wir die folgende Nachricht:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
access-token: EXAMPLE-ACCESS-TOKEN-2
token-type: Bearer
client: EXAMPLE-CLIENT-ID
expiry: 1615311367
uid: api-user@example.com
ETag: W/"ba0df406b647bd92f0bf3a18916714c1"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 35a26441-ae78-48fa-8b2e-e92d2605133b
X-Runtime: 0.167748
Transfer-Encoding: chunked
{"data": [
{"id":1,"name":"860000000000001","equipment_brand_name":"Corrector BK","phone":"","equipment_id":1},...
 ],
"total_pages":7,
"current_page":2
}

Zum Abschluss der Arbeit können Sie die SignOut-Prozedur verwenden oder die benötigten Header der letzten Anfrage speichern und sie, sofern die Gültigkeitsdauer des Tokens nicht abgelaufen ist, beim nächsten Mal wiederverwenden.

Beenden einer Sitzung:

curl -i --header "access-token: EXAMPLE-ACCESS-TOKEN-2" \
 --header "token-type: Bearer" \
 --header "client: EXAMPLE-CLIENT-ID" \
 --header "uid: api-user@example.com" \
 --request DELETE \
 https://api.vadsro.eu/api/v1/auth/sign_out
HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Referrer-Policy: strict-origin-when-cross-origin
Content-Type: application/json; charset=utf-8
ETag: W/"c955e57777ec0d73639dca6748560d00"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: b4b69ac3-5cba-4e6e-b6a0-f6577298c166
X-Runtime: 0.141467
Transfer-Encoding: chunked
{"success":true}

Nächste Schritte

Nun, da Sie sich authentifizieren können, erkunden Sie die zentralen Ressourcen der API: