DEV Community

Cover image for Apidog: Globale Parameter einstellen – Auth-Header für jede Anfrage senden
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Apidog: Globale Parameter einstellen – Auth-Header für jede Anfrage senden

Sie haben vierzig Endpunkte in einem Projekt, und jeder Aufruf benötigt dieselben Header: Authorization: Bearer ... und X-Api-Version. Diese Header manuell pro Anfrage zu pflegen ist fehleranfällig: Ein Endpunkt erhält das Token nicht, ein anderer verwendet eine abweichende API-Version, und ein 401-Fehler tritt nur auf einigen Routen auf.

Apidog noch heute ausprobieren

Mit Apidog können Sie gemeinsame Parameter einmal definieren und automatisch auf passende Anfragen anwenden. In diesem Leitfaden konfigurieren Sie projektweite Header, speichern Tokens als Variablen und verwenden bei Bedarf einen Header nur innerhalb eines Ordners. Anschließend prüfen Sie in der tatsächlichen Anfrage, ob die Header wirklich gesendet wurden. Für den Hintergrund zu Variablen siehe auch Variablen in Apidog beherrschen.

Die Idee ist ein übliches HTTP-Muster: Jede Anfrage führt einen Satz von Schlüssel/Wert-Paaren mit. Die MDN-Referenz zu HTTP-Headern beschreibt diese Mechanik. Apidog ermöglicht es, gemeinsame Werte zentral statt pro Endpunkt zu pflegen.

Was globale Parameter bedeuten

Ein globaler Parameter gilt für das gesamte Projekt, nicht nur für einen einzelnen Endpunkt. Sie definieren ihn einmal, und Apidog fügt ihn automatisch zu passenden Anfragen hinzu.

Globale Parameter können an vier Stellen eingefügt werden:

  • Header für Werte wie Authorization oder X-Api-Version
  • Cookies für Session-Cookies
  • Abfrageparameter für Werte wie ?api_key=...
  • Body-Parameter für Felder, die jeder Request-Body enthalten soll

Für einen Authentifizierungs-Header wählen Sie Header.

Globale Parameter haben eine niedrigere Priorität als Parameter auf Endpunktebene. Definiert ein Endpunkt bereits einen eigenen Authorization-Header, verwendet Apidog diesen spezifischen Wert statt des globalen Standardwerts.

Das macht globale Parameter sicher für große Projekte: Sie liefern einen Standardwert, überschreiben aber keine absichtlich abweichenden Endpunkt-Konfigurationen.

Globale Header für alle Anfragen konfigurieren

Ziel: Alle Endpunkte sollen automatisch diese Header erhalten:

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

1. Umgebungsverwaltung öffnen

Öffnen Sie oben rechts die Umgebungsverwaltung (Environment Management). Dort konfigurieren Sie projektweite Parameter.

Die Apidog-Dokumentation beschreibt diesen Bereich als zentralen Ort für Werte, die Anfragen projektweit begleiten.

2. Header als Parameterposition wählen

Wählen Sie Header.

Die gleiche Oberfläche funktioniert auch für Cookies, Query-Parameter und Body-Felder. Für Authentifizierung und API-Versionierung benötigen Sie jedoch Header.

3. Authorization hinzufügen

Erstellen Sie einen globalen Header mit diesen Werten:

Feld Wert
Name Authorization
Typ String
Standardwert Bearer {{token}}
Beschreibung Bearer-Token für alle authentifizierten Endpunkte.

Verwenden Sie nicht den echten Token als festen Standardwert. Die Variable {{token}} wird im nächsten Abschnitt eingerichtet.

4. X-Api-Version hinzufügen

Fügen Sie einen zweiten globalen Header hinzu:

Feld Wert
Name X-Api-Version
Typ String
Standardwert 2024-08-01
Beschreibung Festgelegte API-Version für jede Anfrage.

5. Parameter aktivieren und speichern

Aktivieren Sie beide Parameter über den Schalter rechts neben dem jeweiligen Eintrag und speichern Sie die Konfiguration.

Danach erben alle Anfragen im Projekt diese Header, sofern der jeweilige Endpunkt keinen gleichnamigen Header selbst definiert.

6. Versand in der tatsächlichen Anfrage prüfen

Verlassen Sie sich nicht nur auf die Konfiguration. Senden Sie eine beliebige Anfrage und öffnen Sie in der Antwortkonsole den Tab Tatsächliche Anfrage (Actual Request).

Dort sehen Sie die Anfrage in der Form, in der sie tatsächlich gesendet wurde — inklusive aufgelöster Variablen:

GET /v1/orders/8842 HTTP/1.1
Host: api.yourservice.com
Authorization: Bearer sk_live_7f3a9c2e1b8d4056
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

Erscheinen beide Header dort, wurden sie mit der Anfrage übertragen.

Token nicht im Header speichern: Variable verwenden

Der Header-Wert sollte so aussehen:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Nicht so:

Authorization: Bearer sk_live_7f3a9c2e1b8d4056
Enter fullscreen mode Exit fullscreen mode

Die Syntax {{token}} referenziert eine Variable. Das Bearer-Schema ist in RFC 6750 definiert; die MDN-Dokumentation zum Authorization-Header beschreibt dessen Verwendung.

Variable token anlegen

  1. Klicken Sie oben rechts auf das Umgebungssymbol (≡).
  2. Öffnen Sie den Bereich Globale Variablen (Global Variables).
  3. Erstellen Sie eine Variable namens token.
  4. Hinterlegen Sie als Wert Ihr Bearer-Token.
  5. Klicken Sie auf Speichern.

Beim Senden löst Apidog den globalen Header auf:

Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

wird zu:

Bearer <Ihr-echtes-Geheimnis>
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie das Ergebnis wieder im Tab Tatsächliche Anfrage.

Die empfohlene Aufteilung lautet:

  • Der globale Parameter definiert den Header-Platz.
  • Die Variable speichert das Geheimnis.

Weitere Details dazu finden Sie im Leitfaden zum API-Client-Umgebungs- und Geheimnismanagement.

Werte je Umgebung wechseln

In realen Projekten benötigen Entwicklung, Tests und Produktion in der Regel unterschiedliche Tokens.

Legen Sie dafür mehrere Umgebungen an, zum Beispiel:

Development
Staging
Production
Enter fullscreen mode Exit fullscreen mode

Wählen Sie die aktive Umgebung über das Dropdown neben dem ≡-Symbol aus. Der globale Header bleibt unverändert:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Nur der aufgelöste Wert von {{token}} ändert sich je Umgebung.

Für weiterführende Authentifizierungs-Setups erklärt der Leitfaden zu Sicherheitsschemata, wie Bearer-, API-Key- und OAuth-Definitionen auf reale Requests abgebildet werden.

Header nur für einen Ordner setzen

Globale Parameter gelten immer für das gesamte Projekt. Das ist nicht passend, wenn nur eine Endpunktgruppe einen zusätzlichen Header benötigt.

Beispiel: Nur Endpunkte unter /admin sollen diesen Header erhalten:

X-Admin-Scope: full
Enter fullscreen mode Exit fullscreen mode

Apidog bietet dafür kein natives Header-Feld in den Ordner-Einstellungen. Verwenden Sie stattdessen ein Pre-Request-Skript auf Ordnerebene:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});
Enter fullscreen mode Exit fullscreen mode

Fügen Sie das Skript in den Pre-Request-Einstellungen des Ordners ein. Jede Anfrage in diesem Ordner erhält dann den Header; Anfragen außerhalb des Ordners bleiben unverändert.

Verwenden Sie diesen Ansatz gezielt für ordnerspezifische Anforderungen. Für projektweite Header sind globale Parameter die einfachere und wartbarere Lösung.

Mehr zum Skripting-Modell finden Sie im Leitfaden zu Pre-Request- und Post-Request-Skripten in Apidog.

Welchen Mechanismus sollten Sie verwenden?

Anforderung Lösung
Header für das gesamte Projekt Globaler Parameter vom Typ Header
Geheimnis nicht im Klartext speichern Umgebungsvariable wie {{token}}
Unterschiedliche Tokens für Dev, Staging und Produktion Umgebungen mit eigenen Variablenwerten
Header nur für eine Endpunktgruppe Pre-Request-Skript auf Ordnerebene
Ein Endpunkt benötigt einen abweichenden Header Header direkt auf Endpunktebene definieren

Achten Sie außerdem auf folgende Punkte:

  • Vermeiden Sie doppelte globale Parameternamen.
  • Verwenden Sie passende Parametertypen.
  • Prüfen Sie Endpunkte mit eigenen Authorization-Headern, da diese den globalen Wert überschreiben.
  • Kontrollieren Sie die endgültige Anfrage immer im Tab Tatsächliche Anfrage.

Workflow mit der Apidog CLI automatisieren

Globale Parameter und Umgebungsvariablen funktionieren nicht nur in der Benutzeroberfläche. Wenn Sie gespeicherte Testszenarien über die CLI ausführen, kann der Lauf eine Umgebung per ID übernehmen.

Damit werden auch diese Werte im CI aufgelöst:

Authorization: Bearer {{token}}
X-Api-Version: 2024-08-01
Enter fullscreen mode Exit fullscreen mode

CLI installieren und anmelden

Die CLI benötigt Node.js v16 oder höher:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Szenario mit einer Umgebung ausführen 

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Die relevanten Optionen:

  • -t: ID des Testszenarios
  • -e: ID der Umgebung
  • -r: Reporter, zum Beispiel cli, html oder junit

Durch -e <env_id> verwendet der Lauf die Variablen der ausgewählten Umgebung. Das bedeutet: Definieren Sie Header und Variable einmal, und Ihre CLI- bzw. CI-Läufe verwenden dieselbe Konfiguration.

Weitere Informationen finden Sie im Leitfaden zur Apidog-CLI-Installation sowie im Walkthrough zu Apidog CLI in GitHub Actions.

FAQ

Überschreiben globale Parameter Endpunkt-Header?

Nein. Endpunkt-Parameter haben eine höhere Priorität. Definiert eine Anfrage ihren eigenen Authorization-Header, wird der globale Header für diese Anfrage nicht verwendet.

Wo sollte das eigentliche Token gespeichert werden?

Speichern Sie es als Umgebungs- oder globale Variable, nicht als Klartext im Header-Standardwert.

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Der tatsächliche Token gehört in die Variable token. Der Leitfaden zum Extrahieren von Variablen mit JSONPath zeigt außerdem, wie Sie Tokens aus Login-Antworten übernehmen und wiederverwenden können.

Wie prüfe ich, ob der Header gesendet wurde?

Senden Sie eine Anfrage und öffnen Sie den Tab Tatsächliche Anfrage (Actual Request). Dort sehen Sie alle tatsächlich gesendeten Header und die aufgelösten Variablenwerte.

Kann ich einen Header nur für einen Ordner definieren?

Ja, über ein Pre-Request-Skript im Ordner:

pm.request.headers.add({
  key: 'X-Admin-Scope',
  value: 'full'
});
Enter fullscreen mode Exit fullscreen mode

Eine native Header-Konfiguration direkt in den Ordner-Einstellungen gibt es dafür nicht.

Benötige ich einen kostenpflichtigen Plan?

Für globale Parameter, Umgebungsvariablen und Pre-Request-Skripte auf Ordnerebene nennt die Dokumentation keine Einschränkung nach Tarifstufe.

Zusammenfassung

Für gemeinsame Header brauchen Sie keine Endpunkte einzeln zu bearbeiten:

  1. Definieren Sie Authorization und X-Api-Version als globale Header-Parameter.
  2. Referenzieren Sie sensible Werte mit Variablen wie {{token}}.
  3. Wechseln Sie Tokens über Umgebungen statt Header-Konfigurationen zu duplizieren.
  4. Prüfen Sie den Versand im Tab Tatsächliche Anfrage.
  5. Verwenden Sie ein Pre-Request-Skript, wenn ein Header nur für einen Ordner gelten soll.

Um die Konfiguration im eigenen Projekt umzusetzen, können Sie Apidog herunterladen und den ersten globalen Header anlegen.

Top comments (0)