API-Dokumentation

Kommunikation

Das Supportsystem verwaltet lediglich die Tickets. Sämtliche Objekte müssen vom Supportsystem bei der Anwendung angefragt werden. Die folgenden Befehle stehen zur Kommunikation zwischen Supportsystem und Anwendung zur Verfügung.

auth Authorisierung eines Benutzers
query Datenanfrage (Objekt oder Liste)
owner Zuständigkeitsanfrage (welcher Benutzer ist der richtige Ansprechpartner für ein Objekt)
edit Datenänderung
action Funktionsausführung
notify Ticket-Meldung

Die Anfragen an das Supportsystem werden via HTTP(S) gestellt. Jede Anfrage enthält ein (vom Administrator) festgelegtes Passwort (pass), das ungewünschte Zugriffe auf die Anwendung verhindert und eine Aktion (do). Das Supportsystem antwortet immer im JSON-Format (Java Script Object Notation).

Authorisierung eines Benutzers (do=auth)

Diesr Befehl wird vom Supportsystem an die Anwendung gesendet, wenn sich ein neuer Benutzer versucht anzumelden. Die Anmeldung erfolgt über eine URL, die von der Anwendung bereitgestellt wird und sowohl Benutzer als auch die Anwendung selbst identifiziert.

Folgende Parameter werden gesendet:

Parameter Wert Beschreibung
pass String Passwort, das der Administrator der Anwendung festgelegt hat
do auth Befehl: Authorisierung eines Benutzers
auth String Authorisierungs-Code, den der neue Benutzer per URL (auth=) mitgeschickt hat

Beispiel:

example.com/?pass=1234&do=auth&auth=K764

Die Anwendung muss daraufhin prüfen, ob der übermittelte Authorisierungs-Code gültig ist und antwortet mit einem fehlerhaften RC (Return-Code) oder folgendem JSON-Konstrukt:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK
profile "user", "mod", "admin" Benutzer-Profil (Benutzer, Moderator oder Administrator)
id Integer Benutzer-ID
name String Name des Benutzers/Moderators/Administrators

Beispiel:

{ "rc"      : 1,
  "profile" : "user",
  "id"      : 10815,
  "name"    : "zodiac2k"
}

Fehler werden durch folgende Return-Codes gemeldet:

RC Fehler
11 Es konnte kein Benutzer gefunden werden, der diesen Auth-Code verwendet.

Zuständigkeitsanfrage (do=owner)

Dieser Befehl wird vom Supportsystem an die Anwendung gesendet, wenn für ein Objekt ein neues Ticket erstellt werden soll. Hier kann die Anwendung einen Benutzer festlegen, der für das Objekt als Ansprechpartner zuständig ist.

Folgende Parameter werden gesendet:

Parameter Wert Beschreibung
pass String Passwort, das der Administrator der Anwendung festgelegt hat
do owner Befehl: Zuständigkeitsanfrage
uid Integer User-ID des ausführenden Moderators/Administrators
entity String Objekt-Typ
id String Objekt-ID

Beispiel:

example.com/?pass=1234&do=owner&uid=10815&entity=item&id=item:995432

Die Anwendung muss daraufhin einen Benutzer auswählen, der für das übermittelte Objekt zuständig sein soll und antwortet mit einem fehlerhaften RC (Return-Code) oder folgendem JSON-Konstrukt:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK
entity String Objekt-Typ
id String Objekt-ID
owner String Besitzer-Objekt-ID
name String Name des Objektes
uid Integer ID des Benutzers
author String Name des Benutzers

Beispiel:

{ "rc"     : 1,
  "entity" : "item",
  "id"     : "item:995432",
  "owner"  : "user:10815",
  "name"   : "Schwert",
  "uid"    : 10815,
  "author" : "zodiac2k"
}

Fehler werden durch folgende Return-Codes gemeldet:

RC Fehler
11 Es konnte kein Benutzer gefunden werden, der diesen Auth-Code verwendet.
21 Der Objekt-Typ ist ungültig.
22 Die Objekt-ID ist ungültig.

Datenänderung (do=edit)

Dieser Befehl wird vom Supportsystem an die Anwendung gesendet, wenn ein Moderator/Administrator eine Änderung an einem Objekt durchführt.

Folgende Parameter werden gesendet:

Parameter Wert Beschreibung
pass String Passwort, das der Administrator der Anwendung festgelegt hat
do edit Befehl: Datenänderung
uid Integer User-ID des ausführenden Moderators/Administrators
entity String Objekt-Typ
id String Objekt-ID
owner String Besitzer-Objekt-ID
name String Name der Objekt-Eigenschaft
old Unbestimmt Wert (vor der Änderung)
new Unbestimmt Wert (nach der Änderung)

Beispiel:

example.com/?pass=1234&do=edit&uid=10815&entity=item&id=item:995432
            &name=pos&old=21&new=22

Die Anwendung muss daraufhin entscheiden, ob die Änderung von einem gültigen Benutzer durchgeführt wurde und ob sie gültig ist. Die Antwort besteht dann aus einem fehlerhaften RC (Return-Code) oder folgendem JSON-Konstrukt:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK

Beispiel:

{ "rc" : 1
}

Fehler werden durch folgende Return-Codes gemeldet:

RC Fehler
11 Es konnte kein Benutzer gefunden werden, der diesen Auth-Code verwendet.
21 Der Objekt-Typ ist ungültig.
22 Die Objekt-ID ist ungültig.
23 Die Objekt-Eigenschaft ist ungültig.
31 Der neue Wert ist ungültig.
32 Der alte Wert stimmt nicht mit dem Datenbestand überein.
33 Neuer und alter Wert stimmen überein - keine Änderung notwendig.

Funktionsausführung (do=action)

Dieser Befehl wird vom Supportsystem an die Anwendung gesendet, wenn ein Moderator/Administrator eine Funktion auf einem Objekt ausführt.

Folgende Parameter werden gesendet:

Parameter Wert Beschreibung
pass String Passwort, das der Administrator der Anwendung festgelegt hat
do action Befehl: Funktionsausführung
uid Integer User-ID des ausführenden Moderators/Administrators
entity String Objekt-Typ
id String Objekt-ID
action String Funktionsbezeichnung
... ... Alle Variablen, die für die Funktion zusätzlich benötigt werden

Beispiel:

example.com/?pass=1234&do=action&uid=10815&entity=item&id=item:995432
            &action=delete

Die Anwendung muss daraufhin entscheiden, ob die Funktion von einem gültigen Benutzer durchgeführt wurde und ob sie gültig ist. Die Antwort besteht dann aus einem fehlerhaften RC (Return-Code) oder folgendem JSON-Konstrukt:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK

Beispiel:

{ "rc" : 1
}

Fehler werden durch folgende Return-Codes gemeldet:

RC Fehler
11 Es konnte kein Benutzer gefunden werden, der diesen Auth-Code verwendet.
21 Der Objekt-Typ ist ungültig.
22 Die Objekt-ID ist ungültig.
24 Die Funktion ist ungültig.
41 Die übergebenen Parameter sind ungültig..

Ticket-Meldung (do=notify)

Dieser Befehl wird vom Supportsystem nur an die Anwendung gesendet, wenn der Administrator diese Meldungen aktiviert hat. Unter Administration kann sowohl die Benachrichtigung für Aktivitäten durch Moderatoren als auch durch Benutzer ein- bzw. ausgeschaltet werden. Dies macht die Benachrichtigung der Benutzer über Änderungen an Tickets via Nachrichten möglich.

Folgende Parameter werden gesendet:

Parameter Wert Beschreibung
pass String Passwort, das der Administrator der Anwendung festgelegt hat
do notify Befehl: Ticket-Meldung
ticket_id Integer ID des Tickets
user_id Integer Ticket-Verantwortlicher
mode "user", "support" Änderung durch Benutzer oder Moderator/Administrator
action "create", "reply", "close", "open", "reject" Erstellung, Antwort, Schließen, Öffnen, Ablehnen
entity String Objekt-Typ
entity_id String Objekt-ID
time Integer Zeitstempel der Änderung
text String Inhalt des Tickets bzw. der Antwort

Beispiel:

example.com/?pass=1234&do=notify&ticket_id=6447&mode=support
            &action=reply&entity=item&id=item:995432&time=877554343235
            &text=Alles+fertig

Das Supportsystem erwartet einen erfolgrechen Return-Code:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK

Beispiel:

{ "rc" : 1
}

Datenanfrage (do=query)

Dieser Befehl wird vom Supportsystem an die Anwendung gesendet, wenn Daten angefragt werde. Dabei kann es sich um eine Liste, ein Objekt oder eine Aktion handeln. Sowohl Listen als auch Objekte müssen unter der Administration angelegt und definiert werden. Hierfür stehen grafische Editoren bereit, mit denen man die gewünschte Darstellung ganz einfach erstellen kann. Aktionen bestehen lediglich aus einem Return-Code und benötigen keine Darstellung.

Listen ermöglichen eine tabellarische Darstellung mehrerer Datensätze. Dabei ist es möglich, Datensätze mit Links zu versehen, um beispielsweise mehr Informationen über einen bestimmten Datensatz zu erlangen. Desweiteren können intern verwendete Werte durch lesbare Beschreibungen ersetzt werden.

Objekte ermöglichen die Darstellung und das Editieren eines Datensatzes. Dabei kann festgelegt werden, welche Werte des Datensatzes verändert werden dürfen. Auch hier können intern verwendete Werte durch lesbare Beschreibungen ersetzt werden. Darüber hinaus können Links in einer Navigation festgelegt werden um beispielsweise Unterobjekte anzuzeigen.

Aktionen ermöglichen die Ausführung von mehr oder weniger komplexen Aktionen, die nicht nur aus einer Datenänderung besteht, beispielsweise das Zurücksetzen eines Passworts, das bei der Anwendung neben der Erstellung eines neuen zufälligen Passworts eine Email an den Benutzer versendet.

Folgende Parameter werden gesendet:

Parameter Wert Beschreibung
pass String Passwort, das der Administrator der Anwendung festgelegt hat
do query Befehl: Datenanfrage
uid Integer User-ID des ausführenden Moderators/Administrators
entity String Objekt-Typ
page Integer Darzustellende Seite der Ergebnismenge
size Integer Anzahl der Datensätze pro Seite
... ... Alle Variablen, die für die Anfrage benötigt werden

Beispiel:

example.com/?pass=1234&do=query&uid=10815&entity=item-list
            &page=1&size=50&user_id=10815

Wenn die Anwendung eine Liste ausgeben soll, muss sie entweder mit einem fehlerhaften RC (Return-Code) oder folgendes JSON-Konstrukt antworten:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK
type "list" Datenanfrage = Liste
entity String Objekt-Typ
total Integer Anzahl der Datensätze (Gesamt)
page Integer Darzustellende Seite der Ergebnismenge
size Integer Anzahl der Datensätze pro Seite
rows Array Array mit den Datensätzen

Beispiel:

{ "rc"     : 1,
  "type"   : "list",
  "entity" : "item-list",
  "total"  : 3,
  "page"   : 1,
  "size"   : 50,
  "rows"   : [ { "id"   : "item:995432", 
                 "name" : "Schwert", 
               },
               { "id"   : "item:898689", 
                 "name" : "Schild",
               },
               { "id"   : "item:942467", 
                 "name" : "Helm",
               }
             ]
}

Wenn die Anwendung ein Objekt ausgeben soll, muss sie entweder mit einem fehlerhaften RC (Return-Code) oder folgendes JSON-Konstrukt antworten:

Variable Wert Beschreibung
rc 1 Return-Code: 1 = OK
type "object" Datenanfrage = Objekt
entity Integer Objekt-Typ
id String Objekt-ID
owner String Besitzer-Objekt-ID
edit Array Array mit allen Felder, die editierbar sind
ticket Boolean Ticket für dieses Objekt erstellbar
data Object Das Objekt mit allen Werte

Beispiel:

{ "rc"     : 1,
  "type"   : "object",
  "entity" : "item",
  "id"     : "item:995432",
  "owner"  : "user:10815",
  "edit"   : [ "name", "pos" ],
  "ticket" : false,
  "data"   : { "name"    : "Schwert", 
               "user_id" : 10815, 
               "pos"     : 11
             }
}

Fehler werden durch folgende Return-Codes gemeldet:

RC Fehler
11 Es konnte kein Benutzer gefunden werden, der diesen Auth-Code verwendet.
21 Der Objekt-Typ ist ungültig.
22 Die Objekt-ID ist ungültig.