API générale: types d'action
auth
Afin d'authentifier l'utilisateur, veuillez utiliser le type d'action auth. Avec votre demande, envoyez le nom d'utilisateur et le mot de passe et vous recevrez un jeton d'authentification en réponse. Le jeton peut ensuite être utilisé pour traiter les demandes ultérieures.
Exemple d'entrée:
{
"action": "auth",
"accessType": 0|1|2|...,
"kname": "...", //Username
"kpass": "...", //Password
"2fa": "...", //optional
"longlife": 0|1 , //optional
"api_key": "" //optional
}
Exemple de sortie:
{
...
"data":
{
"kmd":"token"
}
}
Enregistrez la valeur trouvée sous kmd
et envoyez-le dans tous les appels ultérieurs à l'API comme valeur d'entrée kmd
.
Remarque: en cas d'authentification à deux facteurs, l'appel à auth
retournera dans un code d'erreur en fonction de la méthode d'authentification si 2fa
n'a pas été envoyé. Si tel est le cas, vous devrez montrer à l'utilisateur une page d'authentification à deux facteurs qui correspond au code d'erreur (par exemple pour entrer le code e-mail ou OTP). Veuillez utiliser le jeton (kmd
) que vous avez reçu et utilisez l'action verifyauth
afin de (re) soumettre le code 2fa.
verifyauth
L'action verifyauth
peut être utilisé pour vérifier si un jeton (kmd) est toujours valide et / ou pour soumettre un code 2fa pour une authentification à deux facteurs.
Exemple d'entrée:
{
"action": "verifyauth",
"accessType": 0|1|2|...,
"token": "...", //Token from auth
"2fa": "...", //2fa code
}
Exemple de sortie:
{
...
"data":
{
"kmd":"token"
}
}
Enregistrez la valeur trouvée sous kmd
et envoyez-le dans tous les appels ultérieurs à l'API comme valeur d'entrée kmd
.
droits
Type d'action rights
peut être utilisé pour avoir une vue d'ensemble des modèles et des actions auxquels l'utilisateur a le droit d'accéder.
Exemple d'entrée:
{
"action": "rights",
"accessType": 0|1|2|...,
"token": "..."
}
Exemple de sortie:
{
...
"data":
[
{
"model": "User",
"actions": ["get","list","update"]
},
{
"model": "Subaccount",
"actions": ["get","list","update","create","delete","deleteinfo"]
}
]
}
liste
Le type d'action list
peut être utilisé pour demander une liste d'entrées d'un modèle spécifique à partir de la base de données. Ce type d'action est destiné à être utilisé pour offrir une vue d'ensemble des éléments à un utilisateur (plutôt que pour afficher des détails spécifiques).
Exemple d'entrée attendu:
{
...
"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
}
Exemple de sortie de réponse:
{
"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
}
}
Les données de sortie se composent d'un data
tableau et un tableau de tête correspondant. Le tableau de données contient les lignes à afficher pour l'utilisateur. Le tableau d'en-tête contiendra les informations spécifiques du titre (par exemple le tri, le texte du titre, etc.) pour chaque colonne du tableau.
Les données d'exemple ci-dessus entraîneraient l'affichage du tableau suivant:
Filtres
filters
propriété dans la requête JSON peut être utilisée pour rechercher des éléments spécifiques ou réduire la liste de sortie. le filters
La propriété se compose d'un tableau d'éléments de filtre. Chaque élément est un objet de la structure suivante:{
"fieldname": "...", // Field the filter should apply to
"comparison": "...", // (optional) Comparison type, see description
"value" : "..." // Value to compare the field to
}
Afin de rechercher dans tous les champs, le fieldname query
peut être utilisé.
Possible comparison
les valeurs sont:
Type de comparaison | Description |
eql |
Égal. Rechercher des lignes où le contenu de fieldname est exactement le même que value . (Ce type est par défaut si comparison n'est pas utilisé dans l'objet.) |
lt |
Plus bas que. Rechercher des lignes où le contenu de fieldname est plus petit que value . |
gt |
Plus grand que. Rechercher des lignes où le contenu de fieldname est supérieure value . |
lte |
Inférieur à / égal. Rechercher des lignes où le contenu de fieldname est plus petit que value ou égal à value . |
gte |
Supérieur à / égal. Rechercher des lignes où le contenu de fieldname est supérieure value ou égal à value . |
like |
Contient. Trouver des lignes où value est contenu dans le contenu de fieldname (en partie ou complètement). |
in |
Est dans la liste. Rechercher des lignes où le contenu de fieldname est exactement le même que l'un des value . Dans ce cas, value devrait être un tableau. |
is |
Est NULL. Rechercher des lignes où le contenu de fieldname is NULL . |
isnot |
Est non nulle. Rechercher des lignes où le contenu de fieldname n'est pas NULL . |
Exemple:
{
...
"filters":
[
{
"fieldname": "age",
"comparison": "gte",
"value" : 27
},
{
"fieldname": "lastname",
"comparison": "like",
"value" : "man"
}
]
}
... trouvera les lignes où age
est égal ou supérieur à 27 et lastname
contient l'homme (par exemple Hofmann ou Superman ou Mandy)
obtenez
Le type d'action get
peut être utilisé pour demander une ou plusieurs entrées d'un modèle spécifique à partir de la base de données lorsque les ID des entrées sont déjà connus. L'utilisation prévue de ce type d'action est d'afficher les données dans un formulaire d'édition. Par conséquent, la réponse fournira également des informations détaillées sur chaque champ.
Exemple d'entrée attendu:
{
...
"model": "...",
"action": "get",
"ids": [...] // Array of IDs
}
Veuillez envoyer un tableau vide de ids
afin d'obtenir uniquement la définition du champ. Cela peut vous aider à créer une nouvelle entrée basée sur la définition du champ.
Exemple de sortie de réponse:
{
"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
}
}
L'exemple ci-dessus pourrait donner un formulaire ressemblant à ceci:
engendrent
Afin de créer de nouveaux entires, vous pouvez utiliser le type d'action create
.
Exemple d'entrée attendu:
{
"action": "create",
"accessType": 1,
"model": "Subaccount",
"ids": [],
"data": {
"intID": "0",
"strLogin": "new User",
"strPass": "ABCabc123!",
"intStatus": "1"
}
}
La sortie d'une mise à jour réussie correspond à l'exemple donné pour le get
type d'action. Exemple de sortie:
{
"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
}
}
Mise à jour
Pour modifier un ou plusieurs entires existants, vous pouvez utiliser le type d'action update
.
Exemple d'entrée attendu:
{
"action": "update",
"accessType": 1,
"model": "Subaccount",
"ids": [ 542 ],
"data":
{
"intID": "542",
"strLogin": "aaa",
"strPass": "abcabc",
"intStatus": "1"
}
}
La sortie d'une mise à jour réussie correspond à l'exemple donné pour le get
type d'action. Exemple de sortie:
{
"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
}
}
En cas d'erreur de mise à jour, le système répondra avec un message d'erreur comme celui-ci:
{
"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"
}
}
effacer
Le type d'action delete
peut être utilisé pour supprimer une ou plusieurs entrées d'un modèle spécifique de la base de données lorsque les ID des entrées sont déjà connus.
Exemple d'entrée attendu:
{
...
"model": "...",
"action": "delete",
"ids": [...] // Array of IDs
}
Exemple de sortie de réponse:
{
"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
}
}