API Request

Überblick

Mit dem Trigger API Request kann ein Workflow von einer externen Webanwendung getriggert werden und Daten empfangen. Hierfür wird in der Baustein-Konfiguration eine Endpunkt-URL als Kommunikationsschnittstelle definiert.

Den Baustein findest du unter: Workflow-Baukasten → WHEN

Beispiel

Dein Workflow soll einen Webhook von einer externen Webanwendung empfangen und eine Aktion auslösen. 

Konfigurationsoptionen

Der Baustein hat folgende Konfigurationsoptionen

1. Name: Bezeichnung des Bausteins
2. Route: Definition der Route der Endpunkt-URL, über welche der Workflow erreicht werden kann.
3. Platzhalter einfügen: Fügt eine Variable in die Route ein (optional).
4. Public: Der Zugriff auf den Endpunkt kann mit oder ohne eine Benutzer-Authentifizierung erfolgen. Für die Authentifizierung ist ein API-Token erforderlich (siehe API-Token erstellen).
   Aktiviert: Der Workflow ist über die Endpunkt-URL öffentlich zugänglich.
   Deaktiviert: Eine tokenbasierte Authentifizierung ist erforderlich.
5. Methods: Definition der erlaubten HTTP-Anfragemethoden:
   • 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. USE A REQUEST?: Automatisiertes Anlegen der Datenstruktur für die zu empfangenden Daten. Hierfür gibt es zwei Herangehensweisen:
   • Triggern des temporären URL-Endpunktes, oder
   • Kopieren und einfügen eines JSON-Objekts.
     
     
7. BODY, QUERY STRING und HEADERS: Manuelles Anlegen der Datenstruktur für die zu empfangenden Daten.

Output des Bausteins

Das request Objekt, der rawBody String, sowie die definierten Daten aus der Konfiguration des Bausteins stehen dir im Workflow als Platzhalter zur Verfügung. Die Daten können aus folgenden Quellen stammen:

• request Objekt inkl. rawBody
• Variablen, die du in der Route genutzt hast
• Daten aus der angelegten Datenstruktur in BODY, QUERY STRING und HEADERS
  
  

Beispiel des rawBody

Für das obige request Objekt, sieht der rawBody beispielsweise folgendermaßen aus:

API Request konfigurieren

1. Öffne den Konfigurationsdialog des Bausteins über mehr→ edit.
    
2. Markiere und lösche die vorgegebene Route im Feld Route und gebe eine neue ein. Optional kannst du über Platzhalter einfügen Variablen in deiner Route verwenden.
   Zum Beispiel: api/v1/add-task-from-slack
   
   
3. Definiere über das Kontrollkästchen Public, ob dein Workflow öffentlich zugänglich ist (aktiviert) oder eine tokenbasierte Authentifizierung erfordert (deaktiviert).
   
   
4. Definiere die Methoden mit welchen der Workflow angesprochen werden darf, indem du die entsprechenden Kontrollkästchen aktivierst.
   
   
5. Definiere die Datenstruktur der zu empfangenden Daten:
   • Manuell über die Parametereinstellungen BODY, QUERY STRING und HEADERS (siehe Datenstruktur anlegen), oder
   • Automatisiert über den Dialog USE A REQUEST? indem du entweder den temporären URL-Endpunkt triggerst, oder ein JSON-Objekt einfügst.
6. Klicke auf SAVE.
   ✓ Die API Request ist konfiguriert.

Tipp

Sobald du einen API Request angelegt hast, findest du die definierte URL des Endpunktes im Workflow-Menü unter Endpunkt-URL

Triggern des temporären URL-Endpunktes

1. Kopiere die URL des temporären Endpunktes aus dem Dialog USE A REQUEST?.
   
   
   
   
2. Sende von der externen Webanwendung aus eine API-Anfrage an den temporären Endpunkt.
   ✓ Nach kurzer Zeit wird dir die Datenstruktur im Feld BODY angezeigt und die Auswahl der Methods wurde entsprechend der Anfrage angepasst.
   
   

Videobeispiel

Im folgenden Video erklärt dir Sarah am Beispiel von Messaging-Dienst Slack, wie du eine externe Webanwendung mit saas.do verbinden kannst.

Verwandte Themen

• Unter API findest du weitere Bausteine, um Schnittstellen anzusprechen.
• Unter Auth findest du Bausteine zur Authentifizierung von Benutzern.

Weitere Informationen

• Was ist eine REST-API?
• API-Token erstellen
• JSON (SELFHTML-Wiki)
  
• HTTP-Anfragemethoden (SELFHTML-Wiki)