DIE GET API ist veraltet
Bitte verwenden Sie für zukünftige Projekte die API V2



Beschreibung

Die GET-API dient dem Bereitstellen von Daten aus VIA.


Folgende Anwendungsfälle sind für diese API geeignet:

  • Zugriff von berechtigter Drittsoftware auf Daten von VIA. Abfragemöglichkeit großer Teile der gespeicherten und aufbereiteten Daten.
  • Zugriff von VIA-Modulen, die nicht am gleichen Ort gehostet/betrieben werden, um Stammdaten synchron zu halten oder sogar auf gleiche Datenbasis zuzugreifen.
  • Import von einer entfernten VIA-Version, bspw. beim Betreiben mehrerer VIA-Instanzen.
  • Möglichkeit für Module auf mehrere VIA-Instanzen zuzugreifen. Bspw. für Schüler-Info-Portal, VU-Modul.
  • Datenabgleich zwischen mehreren Trägern für Kostenoptimierungen.

Zu einem GET-Aufruf können mehrere Parameter übergeben werden. Diese werden durch VIA verarbeitet und es wird ein JSON-, CSV-, XML oder HTML-Objekt zurückgegeben, welches durch die aufrufende Instanz weiterverarbeitet werden kann.


Die einzelnen Schnittstellen-Funktionen sind in den System-Einstellungen von VIA frei definierbar. Ebenso die Rückgabe-Werte können durch den Anwender selbst festgelegt werden.


Schlägt der Aufruf fehl, weil bspw. der Parameter-Wert nicht gefunden werden kann oder das Ergebnis nicht eindeutig ist, wird ein HTTP-Error oder ein JSON mit einem Error-Objekt zurückgegeben.


VIA muss zur Verwendung nicht geöffnet sein. VIA stellt zudem beim Aufruf der GET-API keine eigene Session her. Die Verbindung zur Datenbank wird nur temporär erzeugt und sofort wieder geschlossen.


Anlegen einer GET-Funktion

GET-Funktionen können frei definiert werden. VIA liefert in der Grundinstallation mehrere Funktionen (siehe verfügbare Funktionen), die verwendet werden können.

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 "GET_API"
    • 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_SELECT-Funktion ein.
    • ANMERKUNG: Es sind nur SELECT-Anweisungen erlaubt. INSERT, UPDATE, ALTER, etc. werden durch VIA geblockt. Für Schreibvorgänge verwenden Sie bitte die SET-API.
  6. Sie können in der Liste rechts Parameter definieren. Parameter können über die Request-URL übergeben werden und im SQL-Query verwendet werden. Diese dienen als Textmarken. Setzen Sie den Parameter-Namen in eckige 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. Klicken Sie auf "Speichern", nun kann diese Funktion verwendet werden.

System-Parameter

System-Parameter sind nicht dynamische Parameter, die jeder GET-Aufruf besitzt.

  1. function_name: erforderlich Definiert den Namen der GET-Funktion. Dies ist der in VIA hinterlegte Aufruf-Name. Er darf keine Leer- oder Sonderzeichen und Umlaute enthalten (Unterstriche erlaubt) und sollte klein geschrieben sein.

  2. api_key: erforderlich Der berechnete und aktuelle API-KEY der Drittanwendung. -> Mehr zu lesen unter Schnittstellen/API-KEY.

  3. output: optional Mit output können Sie steuern, wie die Daten zurückgegeben werden.

    Folgende Output-Typen existieren:

    • json: standart Gibt ein JSON-Objekt zurück
    • html: Gibt eine mit HTML formatierte Tabelle zurück
    • xml: Gibt ein XML-Objekt zurück
  4. parameter: optional Sie können weitere Parameter übergeben. Dies dient, um bspw. Abfrage-Variablen zu übergeben, wie bspw. IDs. Die Parameter können dann in der GET-Funktion verwendet werden.


Syntax

Wenn VIA über eine Standalone-Installation betrieben wird (Windows, OSX, Linux (Prozess))

// Schema
[http://][IP oder Domain]:[Port]/api/get?[function_name]=[Funktionsname]&[Paramtername]=[Parameterwert] 

// Example
http://10.12.12.1:9416/api/get?function_name=get_schueler_by_snr&snr=12345678 &output=xml



Status

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
  • 302 Found Der Aufruf wurde gefunden und kann ausgeführt werden.
  • 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.
  • 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.

Vordefinierte Funktionen

VIA bietet in der Grundinstallation einige bereits definierte Funktionen. Diese müssen manuell aktiviert werden. Gehen Sie dabei wie unter "Anlegen einer GET-Funktion" vor.