Allgemeine API: Aktionstypen

vorauthentifizieren

Um einen Benutzer zu authentifizieren, fragen Sie bitte den Aktionstyp ab preauth erste. Senden Sie mit Ihrer Anfrage den Benutzernamen und Sie erhalten die Information, ob sich der Benutzer per Passwort und/oder 2Factor anmelden muss oder eine Umleitung auf einen Drittanbieter-Server (SAML/OAuth) erforderlich ist.

Eingabebeispiel:

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

Ausgabebeispiel:

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

Die Antwort enthält folgende Informationen:

Hinweis: Wenn a sso_redirect URL vorhanden ist, müssen Sie den Benutzer zur Authentifizierung an den SSO-Endpunkt weiterleiten. Sobald der Benutzer zurückkehrt, können Sie mit den nächsten Authentifizierungsschritten fortfahren.

Hinweis: In Fällen, in denen E-Mail oder SMS als Zwei-Faktor-Authentifizierung verwendet werden, sendet das System die E-Mail/SMS automatisch mit der Preauth-Anfrage.

auth

Um den Benutzer zu authentifizieren, verwenden Sie bitte den Aktionstyp auth. Senden Sie mit Ihrer Anfrage den Benutzernamen und das Passwort (und ggf. 2FA-Code) und Sie erhalten als Antwort ein Authentifizierungstoken. Der Token kann dann verwendet werden, um nachfolgende Anfragen zu bearbeiten.

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.

Verifizierungsauth

Die Aktion verifyauth kann verwendet werden, um entweder zu überprüfen, ob ein Token (kmd) noch gültig ist und/oder einen 2fa-Code für die Zwei-Faktor-Authentifizierung vorzulegen.

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.

Abmeldung

Der logout Aktion beendet eine bestehende Sitzung (Logout).

Eingabebeispiel:

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

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
 //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)
}

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

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:

Umgerechnete Werte

Für Felder vom Typ Liste (Felduntertypen 1, 2 und 12) können Sie das Suffix verwenden :convert in cols Eigenschaft der Anfrage, um statt des Rohwertes den lesbaren Wert des Inhalts zu erhalten (zB den Namen einer Spalte statt der ID). Wird eine Spalte mit diesem Suffix gefunden, enthält die Ausgabe die Spalte zweimal, einmal als Rohwert und einmal als konvertierten Wert.

Erwartetes Eingabebeispiel:

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

Ausgabebeispiel für eine Antwort:

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

Filter

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

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

Bitte beachten Sie, dass create schlägt fehl, wenn das Modell mit derselben ID bereits vorhanden ist. Wenn Sie bestehende Einstellungen überschreiben möchten, können Sie die beiden Felder senden insertIgnore (Wert=1) und/oder onDuplicateUpdate (Wert=1). Senden insertIgnore weist das System an, keinen Fehler zurückzugeben, wenn das Einfügen fehlschlägt. onDuplicateUpdate weist das System an, alle Werte zu aktualisieren, falls ein Artikel mit derselben ID vorhanden ist.

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