Zum Hauptinhalt springen

API Request erstellen

API Requests ermöglichen es Ihren Custom Widgets, sich mit externen Datenquellen und Diensten zu verbinden. Dieser Leitfaden zeigt Ihnen, wie Sie API Requests im Widget Builder erstellen und konfigurieren. Diese Anleitung gilt sowohl für das separate API Request Formular als auch für das Formular in Custom Widgets.

Einen neuen API Request erstellen​

  1. Navigieren Sie in der Widget Builder Oberfläche zum „API" Tab in Ihrem Widget-Projekt.
  2. Klicken Sie auf die Schaltfläche „+ New API Request".
  3. Geben Sie Ihrem API Request einen aussagekräftigen Namen (z. B. „Get Twitter Feed" oder „Fetch Weather Data").

Den Request konfigurieren​

Grundkonfiguration​

  • URL: Geben Sie die vollständige Endpunkt-URL Ihrer API ein (z. B. https://api.example.com/data)
  • Method: Wählen Sie die passende HTTP-Methode (GET, POST, PUT, DELETE usw.)
  • Headers: Fügen Sie erforderliche Headers hinzu, wie Content-Type: application/json
  • Body: Fügen Sie einen Body hinzu, z. B. als JSON oder Text

Authentifizierung​

Sie können Staffbase-Authentifizierungstoken in Ihren Requests verwenden, indem Sie die Handlebars Helpers nutzen:

// For ID token Authorization:
{{staffbaseIdToken}}
// For access token Authorization:
{{staffbaseAccessToken}}

Weitere Details finden Sie im Leitfaden Use Authentication Tokens.

Um die Authentifizierungsdaten in den Headers oder im Body zu verbergen, können Sie die Option Route through Widget Builder aktivieren.

Handlebars verwenden​

Die Handlebars Helpers und Daten sind für die Felder URL, Headers und Body aktiviert. Sie können diese Helpers nutzen, um Daten zu manipulieren, JSON zu formatieren und Authentifizierungstoken zu verarbeiten.

Hier einige Beispiele, weitere Informationen finden Sie auf der Seite Handlebar Helpers

{{! Convert an object to JSON string }}
{{json settings.complexObject}}

{{! URL encode a string }}
https://api.example.com/search?q={{encode settings.searchTerm}}

{{! Decode and use JWT token data }}
{{#with (decode_jwt staffbaseIdToken)}}
  {{! Now you can access properties from the decoded token }}
  "userId": "{{sub}}", "email": "{{email}}"
{{/with}}

{{! Extract specific fields from JWT token }}
"userId": "{{extract_jwt staffbaseIdToken "sub"}}"

Beispiel: POST Request Body mit Benutzerdaten

{ "user": { "id": "{{extract_jwt staffbaseIdToken "sub"}}", "name": "{{settings.userName}}",
"preferences":
{{json settings.userPreferences}}
}, "timestamp": "{{formatDate "yyyy-MM-dd"}}" }

Request Body​

Für POST-, PUT- und PATCH-Requests können Sie den Request Body konfigurieren:

  1. Wählen Sie den passenden Content-Type (z. B. JSON, Formulardaten, Rohtext) in den Headers.
  2. Geben Sie die Daten ein, die Sie senden möchten
{
  "user": "example",
  "message": "Hello from Widget Builder"
}

Query-Parameter​

Für GET-Requests oder um URL-Parameter hinzuzufügen, verwenden Sie den Bereich für Query-Parameter:

  • Fügen Sie Schlüssel-Wert-Paare hinzu, die an Ihre URL angehängt werden
  • Beispiel: Das Hinzufügen von key=value führt dazu, dass ?key=value an Ihre URL angehängt wird

Variablen verwenden​

Sie können Ihre API Requests dynamisch gestalten, indem Sie Variablen einbinden:

  • Widget Settings: {{{settings.yourSetting}}}
  • Custom Variables: {{{variables.yourVariable}}}
  • Handlebars Helpers: {{{formatDate 'yyyy-MM-dd'}}}

Beispiel-URL mit Variablen:

https://api.weather.com/forecast?location={{{settings.location}}}&date={{{formatDate 'yyyy-MM-dd'}}}

Den Request testen​

Bei jeder Änderung im Formular werden die Daten automatisch neu abgerufen.

  1. Klicken Sie auf die Schaltfläche „Load data", um die Antwort Ihrer API zu sehen
  2. Die Antwort wird im „Response"-Panel angezeigt

Die Antwortdaten verwenden​

Nachdem Sie Ihren API Request eingerichtet haben, können Sie die Antwortdaten in Ihrem Widget-Layout verwenden:

<div class="weather-widget">
  <h2>Weather for {{data.location}}</h2>
  <div class="temperature">{{data.temperature}}°C</div>
  <div class="description">{{data.description}}</div>
</div>

Die Daten aus Ihrer API-Antwort sind unter data verfügbar.

Tipps für API Requests​

  • Rate Limits: Beachten Sie API-Rate-Limits, insbesondere beim Testen
  • CORS: Stellen Sie sicher, dass die API Anfragen von Ihrer Domain erlaubt (CORS aktiviert)