JSON API Call

Überblick

Der Baustein JSON API Call versendet eine Request an eine externe Webanwendung. Mit dieser Request kannst du Informationen senden und anfordern sowie eine Rückmeldung erhalten.

Den Baustein findest du unter: Workflow-Baukasten → DO → API

Beispiel

Bei einem externen Zahlungsdienst sollen Daten zum Zahlungsverkehr eines Kunden abgefragt werden.

Konfigurationsoptionen

Der Baustein hat folgende Konfigurationsoptionen:

1. Name: Bezeichnung des Bausteins
2. Placeholders: Liste der verfügbaren Platzhalter
3. USE A CURL COMMAND?: Automatisiertes Anlegen der Baustein-Konfiguration
4. URL: Endpunkt-URL der externen Webanwendung
5. Method: Definition der HTTP-Anfragemethode:
   • GET: Daten abrufen
   • POST: Daten übermitteln
   • PUT: Daten ersetzen
   • PATCH: Daten partiell ändern
   • DELETE: Daten löschen
     Weitere Informationen zu HTTP-Anfragemethoden findest du auf der Webseite SELFHTML-Wiki.
6. Authentication: Definition des Authentifizierungsschemas:
   • None or Header: Es soll keine Authentifizierung erfolgen oder die Authentifizierung wird im Header der Anfrage mitgeschickt (z. B. ein Bearer-Token).
   • Basic HTTP: Standard-Authentifizierung über Benutzername und Passwort
   • Digest: Hashwertauthentifizierung über Benutzername und Passwort
     Weitere Informationen zur HTTP-Authentifizierung findest du auf Wikipedia.
7. Headers: Definition der Informationen, die im Header gesendet werden sollen
   • Durch einen Zeilenumbruch können bei der Eingabe auch mehrere Header gesetzt werden
     • Ein Anwendungsbeispiel ist Angabe von Authorization und Content-Typeim Header.
       Header-Beispiel

       Authorization: Bearer xyz
       Content-Type: application/json; charset=UTF-8

   • Die Verwendung von Platzhaltern innerhalb des Headers ist ebenfalls möglich
8. Continue on errors: Wenn aktiviert, läuft der Workflow trotz einer Fehlermeldung der Gegenstelle weiter und wird nicht abgebrochen
9. Request is JSON?: Wenn aktiviert, wird die definierte Struktur im REQUEST BODY im JSON-Format gesendet
10. Request is raw file?: Wenn aktiviert, kann anstelle einer Datenstruktur im REQUEST BODY eine Datei (z. B. PDF) im Rohdatenformat gesendet werden
11. REQUEST BODY, RESPONSE SCHEMA und RESPONSE HEADERS: Anlegen der Datenstrukturen für die Daten, die gesendet und empfangen werden

Output des Bausteins

Die definierten Daten aus der Konfiguration des Bausteins stehen dir im weiteren Verlauf des Workflows als Platzhalter zur Verfügung. Die Daten können aus folgenden Quellen stammen: 

• RESPONSE SCHEMA
• RESPONSE HEADER
• Rückmeldung der Gegenstelle (status_code) entsprechend der HTTP Statuscodes (externer Link)

JSON API Call konfigurieren

1. Öffne den Konfigurationsdialog des Bausteins über mehr→ edit.
   
   
2. Gib im Feld Name eine treffende Bezeichnung ein.
   Zum Beispiel: „JSON API Call Zahlungsdienst“
   
   
3. Wenn du einen Curl Command finden konntest:
   • Klicke auf USE A CURL COMMAND?
   • Kopiere den Curl Command aus der Schnittstellenbeschreibung der externen Webanwendung und füge ihn in das Feld ein.
   • Klicke auf USE.
     
     
     ✓ Die Felder aus dem Curl Command wurden im Konfigurationsdialog automatisch gesetzt. Prüfe die Inhalte in den Feldern und bearbeite die offenen Konfigurationsoptionen anhand der folgenden Schritte.
4. Wähle unter Method die HTTP-Anfragemethode mit der die externe Webanwendung angesprochen werden soll.
   
   
5. Wähle unter Authentication die Art der Authentifizierung. Wenn du Basic HTTP oder Digest auswählst, werden dir zusätzlich die Felder Username und Password angezeigt.
   
   
   
   
6. Setze je nach Art der Authentifizierung in den Feldern Username, Password und Headers die entsprechenden Daten.
   
   
7. Aktiviere das Kontrollkästchen Continue on errors?, wenn du möchtest, dass der Workflow im Falle einer Fehlermeldung der Gegenstelle weiterläuft und nicht abgebrochen wird.
   
   
8. Aktiviere das Kontrollkästchen Request is JSON?, wenn die Daten im REQUEST BODY im JSON-Format geschickt werden sollen.
   
   
9. Aktiviere das Kontrollkästchen Request is raw file?, wenn du eine Datei im RAW-Format versenden möchtest. In diesem Fall ändert sich die Eingabemaske unter REQUEST BODY. Das Feld File wird dir angezeigt, in das du den entsprechenden File-Container aus deinen Platzhaltern einfügen kannst.
   
   
   
   
10. Definiere unter REQUEST BODY die Struktur der zu sendenden Daten. Siehe auch Datenstruktur manuell anlegen.
    
    
    
    
11. Definiere unter RESPONSE SCHEMA die Struktur der Daten, die du zurückbekommst. Hierbei gibt es zwei Herangehensweisen:
    • Manuelles Anlegen der Datenstruktur
    • Automatisiertes Anlegen der Datenstruktur über Use a schema?
      
      
      
      
12. Definiere unter RESPONSE HEADER die Struktur der Daten, die du im Header zurückbekommst.
    
    
13. Klicke auf SAVE.
    ✓ Der Baustein ist konfiguriert.

Multipart Request

Um einen Multipart Request auszulösen, kannst du ebenfalls den JSON API Call Baustein benutzen:

1. Definiere unter Headers den Content-Type und die boundary.
2. Aktiviere das Kontrollkästchen Request is raw file?.
3. Befülle das Feld File mit einem String, in welchem du den Multipart Request aufgebaut hast.

In diesem Video zeigen wir dir, wie du den JSON API Call Baustein konfigurieren musst und wie du den MultiPart String aufbauen kannst:

Verwandte Themen

• Datenstruktur anlegen
• API Request
• XML API Call
• JSON Response

Weitere Informationen

• Was ist eine REST-API?
• Was ist ein Bearer Token? Beispiel einer API Autorisierung über HTTP (externe Webseite)
• JSON (SELFHTML-Wiki)