Algemene API: actietypen

vooraf autoriseren

Vraag het actietype op om een ​​gebruiker te authenticeren preauth eerst. Stuur bij uw verzoek de gebruikersnaam mee en u ontvangt informatie of de gebruiker moet inloggen via wachtwoord en/of 2Factor of dat een doorverwijzing naar servers van derden (SAML/OAuth) noodzakelijk is.

Invoervoorbeeld:

{
  "action":     "preauth",
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username  
  "api_key":    ""         //API-Key
}

Uitvoervoorbeeld:

{
  ...
  "data":
  {
    "sso_type":          0/1/2/3,
    "sso_redirect":      "https://...",
    "twofactor_type":     0/1/2/3,
    "twofactor_required": true|false
  }
}

Het antwoord bevat de volgende informatie:

Opmerking: wanneer een sso_redirect URL aanwezig is, moet u de gebruiker doorsturen naar het SSO-eindpunt voor verificatie. Zodra de gebruiker terugkeert, kunt u doorgaan met de volgende authenticatiestappen.

Opmerking: in gevallen waarin e-mail of sms wordt gebruikt als tweefactorauthenticatie, zal het systeem automatisch de e-mail/sms verzenden met het preauth-verzoek.

auth

Gebruik het actietype om de gebruiker te authenticeren auth. Stuur bij uw verzoek de gebruikersnaam en het wachtwoord (en eventueel 2FA-code) mee en u ontvangt als reactie een authenticatietoken. Het token kan vervolgens worden gebruikt om volgende verzoeken te verwerken.

Invoervoorbeeld:

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

Uitvoervoorbeeld:

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

Sla de gevonden waarde op onder kmd en stuur het in alle volgende aanroepen naar de API als invoerwaarde kmd.

Let op: in het geval van Two Factor Authentication, de oproep naar auth zal terugkeren in een foutcode, afhankelijk van de authenticatiemethode als 2fa is niet verzonden. Als dat het geval is, moet u een Two Factor Authentication-pagina aan de gebruiker laten zien die overeenkomt met de foutcode (bijvoorbeeld voor het invoeren van de e-mailcode of OTP). Gebruik het token (kmd) die u heeft ontvangen en actie ondernemen verifyauth om de 2fa-code (opnieuw) in te dienen.

verifieerauth

De actie verifyauth kan worden gebruikt om te controleren of een token (kmd) nog geldig is en/of om een ​​2fa-code in te dienen voor tweefactorauthenticatie.

Invoervoorbeeld:

{
  "action":     "verifyauth",
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
  "2fa":        "...",     //2fa code    
}

Uitvoervoorbeeld:

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

Sla de gevonden waarde op onder kmd en stuur het in alle volgende aanroepen naar de API als invoerwaarde kmd.

uitloggen

De logout actie beëindigt een bestaande sessie (uitloggen).

Invoervoorbeeld:

{
  "action":     "logout",
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
}

rechten

Actie type rights kan worden gebruikt om een ​​overzicht te krijgen van modellen en acties waartoe de gebruiker toegangsrechten heeft.

Invoervoorbeeld:

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

Uitvoervoorbeeld:

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

lijst

Het actietype list kan worden gebruikt om een ​​lijst met vermeldingen van een specifiek model uit de database op te vragen. Dit actietype is bedoeld om te worden gebruikt om een ​​overzicht van items aan een gebruiker te bieden (in plaats van specifieke details te tonen).

Verwacht invoervoorbeeld:

{
  ... 
 "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
 //optional: "assoc": true // If set, returns and associative array instead of a data list
 //optional: "dataonly": true // If set, returns the data list only (no header information)
}

Uitvoervoorbeeld van reactie:

{
  "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":    
    [
      {        
        "headline":     "ID",
        "colsort":      false,
        "colorder":     "intID",
        "colname":      "intID"
      },
      {
        "headlineType": "string",
        "headline":     "Nutzername",
        "colsort":      false,
        "colorder":     "strLogin",
        "colname":      "strLogin"
      },
      {
        "headlineType": "string",
        "headline":     "Status",
        "colsort":      false,
        "colorder":     "intStatus",
        "colname":      "intStatus"
      }
    ],
    "caption": "User",
    "count":   2,
    "total":   2
  }
}

De uitvoergegevens bestaan ​​uit een data array en een bijbehorende head-array. De gegevensmatrix bevat de rijen die aan de gebruiker moeten worden weergegeven. De head-array bevat de specifieke headline-informatie (bijvoorbeeld sortering, headline-tekst enzovoort) voor elke kolom van de tabel.

De bovenstaande voorbeeldgegevens zouden ertoe leiden dat de volgende tabel wordt weergegeven:

Geconverteerde waarden

Voor velden van typelijst (veldsubtypen 1, 2 en 12) kunt u het achtervoegsel gebruiken :convert in cols eigenschap van het verzoek om de leesbare waarde van de inhoud te krijgen in plaats van de onbewerkte waarde (bijvoorbeeld de naam van een kolom in plaats van de ID). Als een kolom met dit achtervoegsel wordt gevonden, bevat de uitvoer de kolom twee keer, één keer als onbewerkte waarde en één keer als geconverteerde waarde.

Verwacht invoervoorbeeld:

{
  ... 
 "model":   "Design",  
 "action":  "list",
 "cols":    ['strName', 'intPosition:convert']  
}

Uitvoervoorbeeld van reactie:

{
 ...
  "data":       
  {
    "data":    
    [
      {
        "id":  "542",
        "row": 
        [
          "myDesign",
          "3",
          "Center middle"
        ]
      },
      ...
    ],
    "head":    
    [
      {        
        "headline":     "name",
        "colsort":      false,
        "colorder":     "strName",
        "colname":      "strName"
      },
      {        
        "headline":     "Position",
        "colsort":      false,
        "colorder":     "intPosition",
        "colname":      "intPosition"
      },
      {        
        "headline":     "Position",
        "colsort":      false,
        "colorder":     "intPosition",
        "colname":      "intPosition:convert"
      }
    ],
   ...
  }
}

filters

{
  "fieldname":  "...", // Field the filter should apply to
  "comparison": "...", // (optional) Comparison type, see description
  "value"    :  "..."  // Value to compare the field to
}

Om in alle velden te kunnen zoeken, moet de veldnaam query kunnen worden gebruikt.

Mogelijk comparison waarden zijn:

Voorbeeld:

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

... vindt rijen waar age is gelijk aan of groter dan 27 en lastname bevat man (bijvoorbeeld Hofmann of Superman of Mandy)

krijgen

Het actietype get kan worden gebruikt om een ​​of meer vermeldingen van een specifiek model uit de database op te vragen wanneer de ID's van de vermeldingen al bekend zijn. Het beoogde gebruik van dit actietype is om de gegevens in een formulier weer te geven voor bewerking. Daarom geeft het antwoord ook gedetailleerde informatie over elk veld.

Verwacht invoervoorbeeld:

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

Stuur een lege array van ids om alleen de velddefinitie te krijgen. Dit kan u helpen om een ​​nieuw item te creëren op basis van de velddefinitie.

Uitvoervoorbeeld van reactie:

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

Het bovenstaande voorbeeld zou kunnen resulteren in een formulier dat er als volgt uitziet:

en je merk te creëren

Om nieuwe entires aan te maken, kunt u het actietype gebruiken create.

Verwacht invoervoorbeeld:

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

De uitvoer van een geslaagde update komt overeen met het voorbeeld dat is gegeven voor de get actie type. Uitvoervoorbeeld:

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

Let op: create mislukt als het model met dezelfde ID al bestaat. Als u bestaande instellingen wilt overschrijven, kunt u de twee velden verzenden insertIgnore (waarde=1) en/of onDuplicateUpdate (waarde=1). Bezig met verzenden insertIgnore zal het systeem vertellen om geen fout te retourneren als het invoegen mislukt. onDuplicateUpdate vertelt het systeem om alle waarden bij te werken in het geval van een bestaand item met dezelfde ID.

-update

Om een ​​of meer bestaande entires te wijzigen, kunt u het actietype gebruiken update.

Verwacht invoervoorbeeld:

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

De uitvoer van een geslaagde update komt overeen met het voorbeeld dat is gegeven voor de get actie type. Uitvoervoorbeeld:

{
  "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 het geval van een updatefout, reageert het systeem met een foutmelding als deze:

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

verwijderen

Het actietype delete kan worden gebruikt om een ​​of meer items van een specifiek model uit de database te verwijderen wanneer de ID's van de items al bekend zijn.

Verwacht invoervoorbeeld:

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

Uitvoervoorbeeld van reactie:

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