🌐

12.2 VIA REST-API (Version 2)

ℹ️ Version 1 der VIA-REST-API ist veraltet und wird nicht weiter entwickelt. Bestehende Schnittstellen auf Version 1 werden weiterhin funktionieren.


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 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 Synchronisierungsvorgänge verwendet werden, wie Berechnungen, Auswertung, Pivotierung, Concatenierung etc.

Es gibt keine Standard-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 "app.{instanz}.via-cloud.de/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.

Alternativ ist es möglich einen statischen Token zu konfigurieren, der zeitlich nicht abläuft. Diese Methode ist einfacher zu implementieren, allerdings auch unsicherer und sollte vor allem zu Testzwecken verwendet werden.


System-Parameter

System-Parameter sind nicht dynamische Parameter, die jeder Aufruf besitzen muss.

  1. api_key:

    erforderlich → der berechnete und aktuelle API-KEY der Drittanwendung. Mehr zu lesen unter Schnittstellen/API-KEY.

    -ODER-

    static_token:

    erforderlich (wenn kein API-Key übergeben) → der statisch zugewiesenen Token zur Verwendung der API
    Verfügbar bei:
    POST, GET, PUT, DELETE

  1. output:

    optional - mit output können Sie steuern, wie die Daten zurückgegeben werden.
    Verfügbar bei:
    GET

    Folgende Output-Typen existieren.

    • jsonStandard → Gibt ein JSON-Objekt zurück
    • html → Gibt eine mit HTML formatierte Tabelle zurück
    • xml → Gibt ein XML-Objekt zurück
    • csv → Gibt die Abfrage im CSV-Format aus. Alle Textumbrüche werden entfernt. Es wird mit Semikolon ; getrennt
    • single → Gibt exakt den Wert aus dem Datenbank-Query (erstes Ergebnis, erste Spalte) zurück ohne ihn in ein Datenformat zu wandeln. Kann verwendet werden, wenn der JSON-Builder von MySQL verwendet werden soll oder wenn das empfangende Programm keine Datenformatierung unterstützt

    Anlegen einer API V2-Funktion

    API-Funktionen können frei definiert werden.

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

    1. Gehen Sie in den Menüpunkt "Daten & Optionen" → "Systemeinstellungen".
    1. Gehen Sie auf den Seitenreiter "Schnittstellen"
      • Sie finden links in der Liste alle verfügbaren Funktionen.
      • Um eine neue Funktion zu erzeugen, klicken Sie auf "Neue Funktion"
    1. Vergeben Sie einen Funktionsnamen. Dieser darf keine Leer- oder Sonderzeichen oder Umlaute (äöüß etc.) enthalten, Unterstriche sind erlaubt. Es sollten Kleinbuchstaben verwendet werden.
    1. 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/Prozeduren 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.
    1. 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. Sie dienen als Variablen und Textmarken.
      1. Sie finden dort auch die Möglichkeit Parameter mit Regular Expressions zu testen und durch die Schnittstelle testen zu lassen. Dadurch kann bereits beim API-Aufruf jedes Datenfeld validiert und ggf. mit ausführlicher Fehlermeldung abgelehnt werden.
      1. Setzen Sie Ihre Parameter-Namen im SQL-Befehl in eckige [] oder geschweifte {} Klammern, wird an dieser Stelle der im der URL übergebene Wert eingesetzt.
    1. Mit der Checkbox rechts oben "Kann verwendet werden" entscheiden Sie, ob diese Funktion aktiviert ist.
    1. Wählen Sie die entsprechende HTTP-Methode (GET, PUT, PUSH, POST) aus.
    1. 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.