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


Beschreibung

Mit der SET-API können Daten ohne Nutzer-Einwirkung in VIA geschrieben werden.


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


Mit der SET-API können Drittprogramme Daten und Änderungen an VIA senden. Sie dient vorzugsweise der Synchronisierung von Stammdaten. VIA überprüft die übergebenen Daten, gleicht den API-Schlüssel ab und spielt die Daten anschließend in das System.


Ist ein SET-Aufruf erfolgreich, gibt VIA ein JSON mit dem Status ok zurück.


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


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


Syntax

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

// Schema:   
[http://][IP oder Domain]:[Port]/api/set?[Parameter-Name]=[Parameter-Wert]

// Example:
http://10.12.12.1:9416/api/set?function_name=set_schueler_data_by_id&id=1812345&parameter1=[parameter1]&parameter2=[parameter2]

System-Parameter

  1. function_name: erforderlich Definiert den Namen der SET-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. parameter: optional Sie können weitere Parameter übergeben. Außerdem sollten Sie die IDs der zu ändernden Datensätze in einem eigenen Parameter übergeben. Die Parameter können Sie in Ihrer SET-Funktion weiter verarbeiten.


Anlegen einer SET-Funktion

SET-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 "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.
  6. Sie können in Liste rechts Parameter definieren. Parameter können über die Request-URL übergeben werden und im SQL-Query verwendet werden. Die 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.

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.