INHALTSVERZEICHNIS


API V2 vs V1

API V2 ersetzt alte Methoden GET, SET und SETJSON
Die API V2 wurde im Juli 2020 veröffentlicht und ersetzt bis dahin vorhandene klassische Schnittstelle mit ihren Methoden GET, SET und SETJSON.

Mit der API V2 können alle Operationen aus der API V1 gleichermaßen ausgeführt werden, ohne spezielle Endpunkte bereit zu stellen.


API V2 setzt jetzt auf die Verwendung der HTTP-Methoden.
In V1 waren alle Aufrufe mit der HTTP-Methode GET auszuführen - auch die Schreibenden Operationen, die über die Endpunkte SET und SETJSON erfolgten.


In V2 werden die HTTP-Methoden wie folgt verwendet:
    GET: selektiert Werte und gibt sie zurück
    PUT: erzeugt Einheiten in VIA und der Datenbank
    POST: verändert bestehende Einheiten in VIA oder der Datenbank
    DELETE: löscht bestehende Einheiten in VIA oder der Datenbank.


Die Authentifizierung erfolgt nicht mehr über die URL-Parameter, sondern über Header-Parameter aber sonst in identischer Form.


Die Benennung der API-Funktion (nicht Methode oder Endpunkt) erfolgt nicht mehr über URL-Parameter, sondern über eigene Endpunkte.

Beschreibung

Die API V2 ist eine Rest-Schnittstelle, die von jeder VIA-Instanz bereit gestellt wird. Mit ihr können Schreib-, Lese-, Änderungs- und Löschvorgänge in VIA ausgelöst werden.


Zur Verwendung der SET-API benötigen Sie einen API-Schlüssel (siehe Sektion API_KEY).


Mit der API V2 können Drittprogramme Daten und Änderungen an VIA senden. Sie dient vorzugsweise der Synchronisierung von Stammdaten, wie Schüler- und Antragsdaten, Unternehmen, Schulen und Haltestellen. Sie kann aber auch für komplexere Synchronisationsvorgänge verwendet werden, wie Berechnungen, Auswertung, Pivotierung, Concatenierung etc.


Es gibt keine Standart-Funktion zum Lesen oder Schreiben von Daten. Jede Funktion wird individuell für das jeweilige Drittprogramm angelegt und an dessen Datenstruktur ausgerichtet.


Dadurch sind Erfolgs- und Fehlermeldungen auch meist individuell, da auch die Datenprüfung und -validierung individuell konfiguriert wird.



Syntax

Pfad:

https://app.{instanz}.via-cloud.de/api/v2/{funktion}?{{parameter}={value}}&{{parameter}={value}}


cURL:

## VIA API V2
curl "http://127.0.0.1:8089/api/v2/student?schueler_id=123456&output=xml" \
     -H 'api_key: 2DF3371D280F24FBDD28E18F48AE8E87' \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8'


Authentifizierung

Die Authentifizierung erfolgt mittels eines Token, der vom aufrufenden Programm berechnet werden muss. Wir nennen diesen Token "api_key". Eine detaillierte Erklärung, wie der api_key generiert wird, erhalten Sie auf Anfrage. Alle weiteren Informationen finden Sie im Artikel API Keys.


Sie können den api_key entweder im Header des Aufrufs (bevorzugt) oder als URL-Parameter übergeben.


Anlegen einer API V2-Funktion 

API-Funktionen können frei definiert werden. 


Zum Anlegen einer neuen Funktion müssen Sie über das Nutzerrecht 4_0_11 verfügen. 


  1. Melden Sie sich bei VIA an. 
  2. Gehen Sie in den Menüpunkt "Daten & Optionen" > "Systemeinstellungen". 
  3. Gehen Sie auf den Seitenreiter "APIs" 
    • Sie finden links in der Liste alle verfügbaren Funktionen. 
    • Um eine neue Funktion zu erzeugen, klicken Sie auf "Neue Funktion" 
  4. Vergeben Sie einen Funktionsnamen. Dieser darf keine Leer- oder Sonderzeichen oder Umlaute (äöüß etc.) enthalten, Unterstriche sind erlaubt. Es sollten Kleinbuchstaben verwendet werden. 
  5. Geben Sie bei "SQL-QUERY" die gewünschte SQL-Funktion ein. 
    • Es empfiehlt sich keine direkten Queries über die Schnittstelle ausführen zu lassen, sondern eine oder mehrere Datenbank-Funktionen zu erstellen, die Sie hier aufrufen.
    • Dies ist empfehlenswert, um Daten besser zu validieren, Fehler zu erkennen und nicht datenbasierte Antworten zurück geben zu können.
  6. Sie können in der Liste rechts Parameter definieren. 
    1. Parameter können über die Request-URL übergeben werden und im SQL-Query verwendet werden. Die dienen als Textmarken.
    2. Sie finden dort auch die Möglichkeit Parameter mit Regular Expressions zu testen und durch die Schnittstelle testen zu lassen.
    3. Setzen Sie Ihre Parameter-Namen im SQL-Befehl in eckige [] oder geschweifte {} Klammern, wird an dieser Stelle der im der URL übergebene Wert eingesetzt. 
  7. Mit der Checkbox rechts oben "Kann verwendet werden" entscheiden Sie, ob diese Funktion aktiviert ist.
  8. Wählen Sie die entsprechende HTTP-Methode (GET, PUT, PUSH, POST) aus.
  9. Klicken Sie auf "Speichern". Nun kann diese Funktion verwendet werden.

Vorgaben zum Verwenden der HTTP-Methoden

API V2 setzt auf eine Standardisierung der Methoden und Funktionen. Aus dem Aufruf soll direkt erkennbar sein, welche Aktion ausgeführt wird, das war u. A. mit V1 nicht möglich.


Die HTTP-Methoden sollen wie folgt genutzt werden:

  • GET: selektiert Werte und gibt sie zurück
  • PUT: erzeugt Einheiten in VIA und der Datenbank
  • POST: verändert bestehende Einheiten in VIA oder der Datenbank
  • DELETE: löscht bestehende Einheiten in VIA oder der Datenbank.


Beispiel:

Sollen Schülerdaten erzeugt werden, so sollte es einen Endpunkt "schueler" oder "student" geben und die verfügbaren Operationen über die HTTP-Methoden gesteuert werden.


FunktionFalschRichtig
Neuen Schüler anlegenGET:
/api/v2/create_student?{parameter=value}
PUT:
/api/v2/student?{parameter=value}
Bestehenden Schüler bearbeitenGET
/api/v2/update_student?{parameter=value}
POST:
/api/v2/student?{parameter=value}
Bestehenden Schüler löschenGET
/api/v2/delete_student?{parameter=value}
DELETE:
/api/v2/student?{parameter=value}
Bestehenden Schüler abfragenGET
/api/v2/get_student?{parameter=value}
GET:
/api/v2/student?{parameter=value}

Rückgabewerte

Jeder Aufruf erhält einen Statuscode zurück. Dieser orientiert sich an den Vorgaben der W3C. http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

  • 200 OK Aufruf ist fehlerfrei ausgeführt worden
  • 201 Created Ein neues Objekt wurde erfolgreich erzeugt
  • 204 No Content Der Aufruf wurde erfolgreich ausgeführt, es gibt aber keinen Rückgabewert.
  • 400 Bad Request Der Aufruf konnte durch den Server nicht ausgeführt werden, existiert aber grundsätzlich. Grund könnten fehlerhafte oder nicht existente Parameter sein.
  • 401 Unauthorized Der Aufruf konnte wegen fehlender Berechtigung nicht ausgeführt werden. Dies deutet auf einen fehlerhaften API_KEY hin.
  • 403 Forbidden Der Server hat den Aufruf verstanden, durfte ihn aber wegen Zugriffsbeschränkungen nicht ausführen.
  • 404 Not Found Die angeforderte URL existiert nicht.
  • 408 Request Timeout Der Server konnte keine Antwort in einer angemessenen Zeit zurückgeben. Der Aufruf wurde aber grundsätzlich zugelassen. Das kann auf zu große Datenmengen oder eine zu schlechte Verbindung zu dem Server hindeuten.
  • 500 Internal Server Error Die VIA-Installation ist beschädigt.