Letzte Aktualisierung: 22.03.2024

Dieses Dokument beschreibt jeden mit der Efecte REST API v1 verfügbaren Endpunkt. Dies ist eine technische Schnittstellenbeschreibung. Die REST API Übersicht finden Sie hier .

Zugriff auf Datenkarten

GET /dc/{templateCode}/data

Alle Datenkarten nach Vorlagencode abrufen – gibt eine paginierte Liste mit Datenkarteninformationen nach angegebener Vorlage zurück.

ANFRAGE

Pfadparameter

Abfrageparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data?filter=%24status%24%20%3D%20%2702%20-%20Solving%27&selectedAttributes=subject%2Cstatus&limit=2&filterId=0&dataCards=true

GET /dc/{templateCode}/data/stream

Gibt alle verfügbaren Datenkarten per Streaming zurück. Bei komplexen und umfangreichen Vorgängen können Streaming-Ergebnisse schnellere und effizientere Ergebnisse liefern als paginierte Daten.

ANFRAGE

Pfadparameter

Abfrageparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data?filter=%24status%24%20%3D%20%2702%20-%20Solving%27&selectedAttributes=subject%2Cstatus&limit=2&filterId=0&dataCards=true

PUT /dc/{Vorlagencode}/Daten

Erstellen oder Bearbeiten mehrerer Datenkarten

ANFRAGE

Pfadparameter

Beispiel

PUT https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data

KÖRPER

[
 {
   "folderCode": "incident_management",
   "dataCardId": "12345",
   "data": {
     "description": {
       "values": [
         {
           "value": "Updating incident"
         }
       ]
     },
     "description": {
       "values": [
         {
           "value": "Description"
         }
       ]
     }
   }
 },
 {
   "folderCode": "incident_management",
   "data": {
     "description": {
       "values": [
         {
           "value": "Creating a new incident"
         }
       ]
     }
   }
 }
]

POST /dc/{templateCode}/data

Erstellen einer neuen Datenkarte

ANFRAGE

Pfadparameter

Abfrageparameter

Beispiel

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data

KÖRPER

 {
   "folderCode": "incident_management",
   "data": {
     "description": {
       "values": [
         {
           "value": "Creating incident"
         }
       ]
     },
     "description": {
       "values": [
         {
           "value": "Description"
         }
       ]
     }
   }
 }

GET /dc/{templateCode}/data/{dataCardId}

Holen Sie sich eine einzelne Datenkarte

ANFRAGE

Pfadparameter

Abfrageparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

LÖSCHEN /dc/{templateCode}/data/{dataCardId}

Löschen einer einzelnen Datenkarte

ANFRAGE

Pfadparameter

Beispiel

DELETE https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

PATCH /dc/{Vorlagencode}/data/{Datenkarten-ID}

Vorhandene Datenkarte bearbeiten

ANFRAGE

Pfadparameter

Abfrageparameter

Beispiel

PATCH https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345

KÖRPER

{
   "folderCode": "incident_management",
   "data": {
     "description": {
       "values": [
         {
           "value": "Creating incident"
         }
       ]
     },
     "description": {
       "values": [
         {
           "value": "Description"
         }
       ]
     }
   }
 }

GET /dc/{Vorlagencode}/data/{Datenkarten-ID}/{Attributcode}

Attribut aus Datenkarte abrufen

ANFRAGE

Pfadparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

PUT /dc/{Vorlagencode}/data/{Datenkarten-ID}/{Attributcode}

Attribut von Datenkarte aktualisieren

ANFRAGE

Pfadparameter

Beispiel

PUT https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

KÖRPER

{
 "values": [
   {
     "value":"Updating subject"
   }
 ]
}

POST /dc/{Vorlagencode}/data/{Datenkarten-ID}/{Attributcode}

Wert aus Datenkarte zum Attribut hinzufügen

ANFRAGE

Pfadparameter

Beispiel

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

KÖRPER

{
 "values": [
   {
     "value":"Adding value to subject"
   }
 ]
}

LÖSCHEN /dc/{templateCode}/data/{dataCardId}/{attributeCode}

Wert des Attributs aus der Datenkarte löschen.

ANFRAGE

Pfadparameter

Beispiel

DELETE https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject

GET /dc/{templateCode}/data/{dataCardId}/{attributeCode}/file/{locationOfExternalData}

Anhang von der Datenkarte herunterladen.

ANFRAGE

Pfadparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject/file/20210512_01

POST /dc/{Vorlagencode}/Daten/{Datenkarten-ID}/{Attributcode}/Datei

Anhang auf die Datenkarte hochladen.

ANFRAGE

Pfadparameter

Beispiel

POST https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident/data/12345/subject/file/20210512_01 -H "Content-Type: multipart/form-data" -F "fileName=example.png" -F "fileUpload=example.png;type=image/png"

Zugriff auf Vorlagen

GET /dc

Liste aller Vorlagen abrufen.

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc

GET /dc/{Vorlagencode}

Vorlage per Code abrufen.

ANFRAGE

Pfadparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/dc/incident

So testen Sie die Schnittstelle

GET /echo

Gibt den Inhalt des Abfrageparameters „message“ zurück. Für Testzwecke.

ANFRAGE

Abfrageparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/echo?message=Hello%20world

GET /echo/jwt

Gibt den Inhalt des Abfrageparameters "message" zurück, wenn das JWT-Token gültig ist. Für Testzwecke.

ANFRAGE

Abfrageparameter

Beispiel

GET https://efecte.efectecloud.com/rest-api/itsm/v1/echo?message=Hello%20world

Fehlerbehebung

REST API Fehler

Im Falle von Fehlern – beispielsweise verursacht durch eine fehlgeschlagene Autorisierung, fehlerhafte Parameter oder eine schlecht formatierte Abfrage – reagiert die API mit einer standardisierten Fehlerantwort:

 {
 "code": 401,
 "message": "Token was empty or not provided. Token should be provided in AUTHORIZATION header.",
 "error": "Unauthorized",
 "url": "https://efecte.efectecloud.com/itsm/api/v1/dc/incident/data?limit=50&filterId=0",
 "timestamp": "2021-12-21T11:41:22Z"
}

Die Antwort enthält immer „Code“, „Fehler“, „URL“ und „Zeitstempel“ und in den meisten Fällen „Nachricht“ mit Einzelheiten zum zugrunde liegenden Problem.

Mögliche Fehler

JWT-Token kann nicht vom Login-Endpunkt abgerufen werden

Um ein JWT-Token zu erhalten, muss dem für die Anmeldung verwendeten Benutzer eine Rolle mit Berechtigung für das Modul „Externe API “ zugewiesen sein. Wenn der Benutzer nicht über die Berechtigungen für das Modul „Externe API verfügt, enthält die Antwort des Anmeldeendpunkts Informationen über unzureichende Berechtigungen.
Wenn Sie eine nicht autorisierte Antwort erhalten, obwohl Benutzername und Kennwort korrekt sind und die Rolle über die richtigen Berechtigungen verfügt, stellen Sie sicher, dass es sich bei dem Konto um ein lokales ESM-Konto handelt.

Das Attribut ist nicht nullbar und wenn Sie ein „“ als Wert senden, ist das Feld nicht mehr leer

Das Attribut vom Typ „String“ enthält die folgenden Optionen: Zeichenfolge | Zahl | Datum

Mit StaticValue:

• Wert: Zeichenfolge
• Code – Zeichenfolge
• Nullwert zulässig – Wahr

Wenn Sie also einen leeren Attributwert über REST API wünschen, verwenden Sie diese Syntax:

"email": {
           "values": [
               {
                   "value": null
               }
           ]
       }