Allgemeine API: Aktionstypen
auth
Um den Benutzer zu authentifizieren, verwenden Sie bitte den Aktionstyp auth. Senden Sie bei Ihrer Anfrage den Benutzernamen und das Passwort und Sie erhalten ein Authentifizierungstoken als Antwort. Das Token kann dann verwendet werden, um nachfolgende Anforderungen zu verarbeiten.
Eingabebeispiel:
{
"action": "auth",
"accessType": 0|1|2|...,
"kname": "...", //Username
"kpass": "...", //Password
"2fa": "...", //optional
"longlife": 0|1 , //optional
"api_key": "" //optional
}
Ausgabebeispiel:
{
...
"data":
{
"kmd":"token"
}
}
Speichern Sie den unter gefundenen Wert kmd
und senden Sie es in allen nachfolgenden Aufrufen an die API als Eingabewert kmd
.
Bitte beachten Sie: Im Falle einer Zwei-Faktor-Authentifizierung rufen Sie an auth
wird abhängig von der Authentifizierungsmethode einen Fehlercode zurückgeben, wenn 2fa
wurde nicht gesendet. In diesem Fall müssen Sie dem Benutzer eine Zwei-Faktor-Authentifizierungsseite anzeigen, die dem Fehlercode entspricht (z. B. zur Eingabe des E-Mail-Codes oder des OTP). Bitte benutzen Sie den Token (kmd
), die Sie erhalten haben und Aktion verwenden verifyauth
um den 2fa-Code (erneut) einzureichen.
verifyauth
Die Aktion verifyauth
kann verwendet werden, um entweder zu überprüfen, ob ein Token (kmd) noch gültig ist, und / oder um einen 2fa-Code für die Zwei-Faktor-Authentifizierung zu senden.
Eingabebeispiel:
{
"action": "verifyauth",
"accessType": 0|1|2|...,
"token": "...", //Token from auth
"2fa": "...", //2fa code
}
Ausgabebeispiel:
{
...
"data":
{
"kmd":"token"
}
}
Speichern Sie den unter gefundenen Wert kmd
und senden Sie es in allen nachfolgenden Aufrufen an die API als Eingabewert kmd
.
Rechte
Aktionstyp rights
kann verwendet werden, um einen Überblick über Modelle und Aktionen zu erhalten, auf die der Benutzer Zugriff hat.
Eingabebeispiel:
{
"action": "rights",
"accessType": 0|1|2|...,
"token": "..."
}
Ausgabebeispiel:
{
...
"data":
[
{
"model": "User",
"actions": ["get","list","update"]
},
{
"model": "Subaccount",
"actions": ["get","list","update","create","delete","deleteinfo"]
}
]
}
Liste
Der Aktionstyp list
kann verwendet werden, um eine Liste von Einträgen eines bestimmten Modells aus der Datenbank anzufordern. Dieser Aktionstyp soll verwendet werden, um einem Benutzer einen Überblick über Elemente zu bieten (anstatt bestimmte Details anzuzeigen).
Erwartetes Eingabebeispiel:
{
...
"model": "...",
"action": "list",
"filters": [...], // Filters to apply, see description (optional)
"limit": 100, // Limit of output rows (optional)
"offset": 0, // Start index of first row (optional)
"order": "...", // Column to sort (optional)
"sort": "asc|desc", // Sorting direction of output (optional)
"cols": [...] // If set, will output the named fields, otherwise a default set of fields will be shown
}
Ausgabebeispiel für eine Antwort:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "list",
"data":
{
"data":
[
{
"id": "542",
"row":
[
"542",
"aaa",
"Aktiv"
]
},
{
"id": "543",
"row":
[
"543",
"bbb",
"Aktiv"
]
}
],
"head":
[
{
"headlineType": "string",
"headline": "ID",
"colsort": false,
"colorder": "intID"
},
{
"headlineType": "string",
"headline": "Nutzername",
"colsort": false,
"colorder": "strLogin"
},
{
"headlineType": "string",
"headline": "Status",
"colsort": false,
"colorder": "intStatus"
}
],
"caption": "User",
"count": 2,
"total": 2
}
}
Die Ausgabedaten bestehen aus a data
Array und ein entsprechendes Head-Array. Das Datenarray enthält die Zeilen, die dem Benutzer angezeigt werden sollen. Das Head-Array enthält die spezifischen Überschrifteninformationen (z. B. Sortierung, Überschriftentext usw.) für jede Spalte der Tabelle.
Die obigen Beispieldaten würden dazu führen, dass die folgende Tabelle angezeigt wird:
Filter
filters
Eigenschaft in der Anforderung JSON kann verwendet werden, um nach bestimmten Elementen zu suchen oder die Ausgabeliste zu reduzieren. Das filters
Die Eigenschaft besteht aus einem Array von Filterelementen. Jeder Gegenstand ist ein Objekt mit folgender Struktur:{
"fieldname": "...", // Field the filter should apply to
"comparison": "...", // (optional) Comparison type, see description
"value" : "..." // Value to compare the field to
}
Um in allen Feldern zu suchen, muss der Feldname query
kann verwendet werden.
Möglich comparison
Werte sind:
Vergleichstyp | BESCHREIBUNG |
eql |
Gleich. Finden Sie Zeilen, in denen Inhalt von fieldname ist genau das gleiche wie value . (Dieser Typ ist Standard, wenn comparison wird im Objekt nicht verwendet.) |
lt |
Niedriger als. Finden Sie Zeilen, in denen Inhalt von fieldname ist kleiner als value . |
gt |
Größer als. Finden Sie Zeilen, in denen Inhalt von fieldname größer ist als value . |
lte |
Niedriger als / gleich. Finden Sie Zeilen, in denen Inhalt von fieldname ist kleiner als value oder gleich value . |
gte |
Größer als / gleich. Finden Sie Zeilen, in denen Inhalt von fieldname größer ist als value oder gleich value . |
like |
Enthält. Suchen Sie Zeilen wo value ist im Inhalt von enthalten fieldname (teilweise oder vollständig). |
in |
Ist in der Liste. Finden Sie Zeilen, in denen Inhalt von fieldname ist genau das gleiche wie einer von value . In diesem Fall value sollte ein Array sein. |
is |
Ist Null. Finden Sie Zeilen, in denen Inhalt von fieldname is NULL . |
isnot |
Ist nicht NULL. Finden Sie Zeilen, in denen Inhalt von fieldname ist nicht NULL . |
Beispiel:
{
...
"filters":
[
{
"fieldname": "age",
"comparison": "gte",
"value" : 27
},
{
"fieldname": "lastname",
"comparison": "like",
"value" : "man"
}
]
}
... finden Zeilen wo age
ist gleich oder größer als 27 und lastname
enthält Menschen (zB Hofmann oder Superman oder Mandy)
bekommen
Der Aktionstyp get
kann verwendet werden, um einen oder mehrere Einträge eines bestimmten Modells aus der Datenbank anzufordern, wenn die IDs der Einträge bereits bekannt sind. Mit diesem Aktionstyp sollen die Daten in einem Formular zur Bearbeitung angezeigt werden. Daher liefert die Antwort auch detaillierte Informationen zu jedem Feld.
Erwartetes Eingabebeispiel:
{
...
"model": "...",
"action": "get",
"ids": [...] // Array of IDs
}
Bitte senden Sie ein leeres Array von ids
um nur die Felddefinition zu erhalten. Dies kann Ihnen helfen, einen neuen Eintrag basierend auf der Felddefinition zu erstellen.
Ausgabebeispiel für eine Antwort:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "get",
"data":
{
"fields":
[
{
"fieldname": "intID",
"displayname": "ID",
"type": 2,
"subtype": 8,
"required": true,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "542",
"displayvalue": "",
"listkeys": [],
"listvalues": []
},
{
"fieldname": "strLogin",
"displayname": "Nutzername",
"type": 1,
"subtype": 0,
"required": true,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "aaa",
"displayvalue": "aaa",
"listkeys": [],
"listvalues": []
},
{
"fieldname": "strPass",
"displayname": "Passwort",
"type": 1,
"subtype": 5,
"required": true,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "%%unchanged%%",
"displayvalue": "********",
"listkeys": [],
"listvalues": []
},
{
"fieldname": "intStatus",
"displayname": "Status",
"type": 2,
"subtype": 1,
"required": false,
"defaultvalue": null,
"disabled": false,
"infotext": false,
"value": "1",
"displayvalue": "Aktiv",
"listkeys": [ 0, 1 ],
"listvalues": [ "Inaktiv", "Aktiv" ]
}
],
"caption": "User: aaa",
"groups": [],
"ids": [ 542 ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}
Das obige Beispiel könnte zu einem Formular führen, das wie folgt aussieht:
erstellen
Um neue Entires zu erstellen, können Sie den Aktionstyp verwenden create
.
Erwartetes Eingabebeispiel:
{
"action": "create",
"accessType": 1,
"model": "Subaccount",
"ids": [],
"data": {
"intID": "0",
"strLogin": "new User",
"strPass": "ABCabc123!",
"intStatus": "1"
}
}
Die Ausgabe eines erfolgreichen Updates entspricht dem Beispiel für das get
Aktionstyp. Ausgabebeispiel:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "get",
"previousAction": "create",
"data":
{
"fields": [...],
"caption": "User: new User",
"groups": [],
"subgroups": [],
"ids": [ 544 ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}
Aktualisierung
Um ein oder mehrere vorhandene Objekte zu ändern, können Sie den Aktionstyp verwenden update
.
Erwartetes Eingabebeispiel:
{
"action": "update",
"accessType": 1,
"model": "Subaccount",
"ids": [ 542 ],
"data":
{
"intID": "542",
"strLogin": "aaa",
"strPass": "abcabc",
"intStatus": "1"
}
}
Die Ausgabe eines erfolgreichen Updates entspricht dem Beispiel für das get
Aktionstyp. Ausgabebeispiel:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "get",
"previousAction": "update",
"data":
{
"fields": [...],
"caption": "User: aaa",
"groups": [],
"subgroups": [],
"ids": [ 542 ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}
Im Falle eines Aktualisierungsfehlers antwortet das System mit einer Fehlermeldung wie der folgenden:
{
"status": "Error",
"statuscode": 113,
"msg": "Update error, see error message. Field specific messages see response.data",
"model": "Subaccount",
"action": "update",
"data":
{
"strLogin": "Wert muss mindestens 6 Zeichen lang sein",
"strPass": "Wert muss Sonderzeichen beinhalten"
}
}
löschen
Der Aktionstyp delete
kann verwendet werden, um einen oder mehrere Einträge eines bestimmten Modells aus der Datenbank zu löschen, wenn die IDs der Einträge bereits bekannt sind.
Erwartetes Eingabebeispiel:
{
...
"model": "...",
"action": "delete",
"ids": [...] // Array of IDs
}
Ausgabebeispiel für eine Antwort:
{
"status": "Success",
"statuscode": 0,
"msg": "Erfolgreich",
"model": "Subaccount",
"action": "create",
"previousAction": "delete",
"data":
{
"fields": [...],
"caption": "User: new User",
"groups": [],
"subgroups": [],
"ids": [ ],
"canDelete": true,
"canSave": true,
"canSaveNew": true
}
}