Info
Content

General API: Action types

auth

In order to authenticate the user please use action type auth. With your request, send the username and password and you will receive an authentication token as response. The token can then be used in order to process subsequent requests.

Input example:

{
  "action":     "auth",
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username
  "kpass":      "...",     //Password
  "longlife":   0|1 ,      //optional
  "lang":       1|2|3|...  
}

Output example:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Save the value found under kmd and send it in all subsequent calls to the API as input value kmd.

rights

Action type rights can be used in order to get an overview on models and actions the user has rights to access.

Input example:

{
  "action":     "rights",
  "accessType": 0|1|2|...,
  "kmd":        "..."
}

Output example:

{
  ...
  "data":
  [
    {
      "model":   "User",
      "actions": ["get","list","update"]
    },
    {
      "model":   "Subaccount",
      "actions": ["get","list","update","create","delete","deleteinfo"]
    }
  ]
}

list

The action type list can be used in order to request a list of entries of a specific model from the database. This action type is intended to be used for offering an overview of items to a user (rather than showing specific details).

Expected input example:

{
  ... 
 "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
}

Output example of response:

{
  "status":     "Success",
  "statuscode": 0,
  "msg":        "Erfolgreich",
  "model":      "Subaccount",
  "action":     "list",
  "data":       
  {
    "data":    
    [
      {
        "id":  "542",
        "row": 
        [
          {
            "content": "542",
            "type":    "string"
          },
          {
            "content": "aaa",
            "type":    "string"
          },
          {
            "content": "Aktiv",
            "type":    "string"
          }
        ]
      },
      {
        "id":  "543",
        "row": 
        [
          {
            "content": "543",
            "type":    "string"
          },
          {
            "content": "bbb",
            "type":    "string"
          },
          {
            "content": "Aktiv",
            "type":    "string"
          }
        ]
      }
    ],
    "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
  }
}

The output data consists of a data array and a corresponding head array. The data array contains the rows to be displayed to the user. The head array will contain the specific headline information (e.g. sorting, headline text and so on) for each column of the table.

The above example data would result in the following table to be displayed:

Filters

The filters property in the request JSON can be used in order to search for specific items or reduce the output list. The filters property consists of an array of filter items. Each item is an object of the following structure:
{
"fieldname": "...", // Field the filter should apply to
"comparison": "...", // (optional) Comparison type, see description
"value" : "..." // Value to compare the field to
}

In order to search in all fields, the fieldname query can be used.

Possible comparison values are:

Comparison type Description
eql Equal. Find rows where content of fieldname is exactly the same as value. (This type is default if comparison is not used in the object.)
lt Lower than. Find rows where content of fieldname is smaller than value.
gt Greater than. Find rows where content of fieldname is greater than value.
lte Lower than/Equal. Find rows where content of fieldname is smaller than value or equal to value.
gte Greater than/Equal. Find rows where content of fieldname is greater than value or equal to value.
like Contains. Find rows where value is contained in the content of fieldname (in part or completely).
in Is in list. Find rows where content of fieldname is exactly the same as one of value. In this case value should be an array.
is Is NULL. Find rows where content of fieldname is NULL.
isnot Is not NULL. Find rows where content of fieldname is not NULL.

Example:

{
  ...
  "filters":
  [
    {
      "fieldname": "age",
      "comparison": "gte",
      "value" : 27
    },
    {
      "fieldname": "lastname",
      "comparison": "like",
      "value" : "man"
    }
  ]
}

... will find rows where age is equal or greater than 27 and lastname contains man (e.g. Hofmann or Superman or Mandy)

get

The action type get can be used in order to request one or more entries of a specific model from the database when the IDs of the entries are already known. The intended use of this action type is in order to display the data in a form for editing. Hence the response will also provide detailed information about each field.

Expected input example:

{
  ... 
 "model":   "...",  
 "action":  "get",
 "ids":     [...]  // Array of IDs
 }

Please send an empty array of ids in order to get the field definition only. This can help you to create a new entry based on the field definition.

Output example of response:

{
  "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":     [],
    "subgroups":  [],
    "ids":        [ 542 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

The above example could result in a form looking like this:

create

In order to create a new entires you can use the action type create.

Expected input example:

{
  "action":     "create",
  "accessType": 1,
  "model":      "Subaccount",
  "ids":        [],
  "data":       {
    "intID":     "0",    
    "strLogin":  "new User",
    "strPass":   "ABCabc123!",
    "intStatus": "1"
  }
}

The output of an successfull update corresponds to the example given for the get action type. Output example:

{
  "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
  }
}

update

In order to change one or more existing entires you can use the action type update.

Expected input example:

{
  "action":     "update",
  "accessType": 1,
  "model":      "Subaccount",
  "ids":        [ 542 ],
  "data":       
  {
    "intID":     "542",
    "strLogin":  "aaa",
    "strPass":   "abcabc",
    "intStatus": "1"
  }  
}

The output of an successfull update corresponds to the example given for the get action type. Output example:

{
  "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
  }
}

In case of an update error, the system will respond with an error message like this:

{
  "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"
  }
}

delete

The action type delete can be used in order to delete one or more entries of a specific model from the database when the IDs of the entries are already known.

Expected input example:

{
  ... 
 "model":   "...",  
 "action":  "delete",
 "ids":     [...]  // Array of IDs
 }

Output example of response:

{
  "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
  }
}
Back to top