Magento GraphQL & REST Endpoints mit PhpStorm HTTP-Client testen

1. Warum der PhpStorm HTTP-Client Postman ersetzt

Der integrierte HTTP-Client von PhpStorm ist kein Notbehelf, sondern ein vollwertiges API-Testing-Werkzeug. Das entscheidende Argument für Magento-Entwickler: die .http-Dateien, in denen die Requests definiert werden, sind schlichte Textdateien und leben damit im Repository. Das bedeutet, dass das gesamte Team dieselben Requests verwendet, neue Endpoints sofort versioniert sind und Reviews über Git-Diffs stattfinden können – statt über Screenshots aus Postman-Collections, die niemand sieht.

Ein weiterer Vorteil ist der direkte Zugriff auf Environment-Variablen ohne den Umweg über ein externes Tool. Wenn der Auth-Token aus einem vorangehenden Request automatisch in den nächsten übernommen wird, entfällt das manuelle Kopieren aus dem Response-Fenster. Das ist besonders bei Magento-APIs relevant, wo ein Customer-Token zuerst über /V1/integration/customer/token angefordert und dann bei allen nachfolgenden Requests im Authorization-Header mitgesendet werden muss.

Der PhpStorm HTTP-Client unterstützt HTTP/1.1, HTTP/2, GraphQL, WebSocket und gRPC. Für Magento 2 sind vor allem REST und GraphQL relevant. Die IDE zeigt Responses mit Syntax-Highlighting, bietet JSON-Pfad-Suche und kann Responses automatisch mit JavaScript-basierten Test-Skripten auswerten. Alles ohne Installation, ohne Account, ohne Cloud-Sync – ein erheblicher Vorteil gegenüber Tools, die Daten auf fremden Servern speichern.

2. .http-Dateien: Grundaufbau und Syntax

Eine .http-Datei enthält einen oder mehrere Requests, getrennt durch drei Rauten (###). Jeder Request besteht aus einer Zeile mit der HTTP-Methode und der URL, optionalen Header-Zeilen und einem optionalen Body nach einer Leerzeile. PhpStorm erkennt .http- und .rest-Dateien automatisch und stellt im Editor Play-Buttons zum direkten Ausführen bereit. Das Ergebnis erscheint in einem geteilten Response-Fenster rechts oder unten, mit JSON-Formatierung und Navigation durch verschachtelte Strukturen.

Variablen werden in doppelt-geschweiften Klammern referenziert: {{base_url}}. Diese Variablen sind in einer separaten http-client.env.json-Datei definiert und nach Environment (dev, staging, prod) gruppiert. Sensible Werte wie Passwörter und Tokens kommen in eine http-client.private.env.json, die in der .gitignore eingetragen ist. So ist die Dateistruktur versioniert, ohne dass Credentials im Repository landen.

### Magento REST API — http-client.env.json
{
  "dev": {
    "base_url": "https://magento.local",
    "store_code": "default",
    "admin_user": "admin"
  },
  "staging": {
    "base_url": "https://staging.mironsoft.de",
    "store_code": "de_de",
    "admin_user": "admin_staging"
  }
}

### http-client.private.env.json (in .gitignore)
{
  "dev": {
    "admin_password": "Admin123!",
    "customer_email": "test@example.com",
    "customer_password": "Test1234!"
  }
}

3. Magento REST: Authentifizierung und Token-Verwaltung

Magento 2 REST-APIs unterscheiden zwischen öffentlichen Endpoints, die keinen Token benötigen, Customer-Endpoints mit Customer-Token und Admin-Endpoints mit Admin-Integration-Token. Für die Entwicklung braucht man primär den Admin-Token. Dieser wird über POST /rest/V1/integration/admin/token mit Username und Passwort im JSON-Body angefordert. Die Antwort ist ein reiner String, der dann als Bearer-Token im Authorization-Header mitgesendet wird.

Das PhpStorm HTTP-Client Scripting erlaubt es, den Token aus der Response automatisch in eine Environment-Variable zu schreiben. Im Response Handler-Block unterhalb des Requests definiert man JavaScript-Code, der nach dem Request ausgeführt wird. So läuft man einmal den Token-Request, und alle nachfolgenden Requests in derselben Session nutzen den extrahierten Token automatisch – ohne manuelles Kopieren.

### POST Admin Token — run this first, token stored automatically
POST {{base_url}}/rest/https://www.mironsoft.de//V1/integration/admin/token
Content-Type: application/json

{
  "username": "{{admin_user}}",
  "password": "{{admin_password}}"
}

> {%
  // Response handler: store token in session variable
  client.test("Token received", function() {
    client.assert(response.status === 200, "Expected HTTP 200");
  });
  // Strip surrounding quotes from the plain-string response
  client.global.set("admin_token", response.body.replace(/"/g, ""));
%}

###

### GET Products — uses stored admin token
GET {{base_url}}/rest/https://www.mironsoft.de//V1/products?searchCriteria[pageSize]=5
Authorization: Bearer {{admin_token}}
Accept: application/json

4. REST-Endpoints systematisch abfragen

Magento 2 REST-API folgt dem Search-Criteria-Pattern: alle Collection-Endpoints akzeptieren Filtergruppen, Sortieroptionen und Paginierungsparameter als Query-Parameter. Im HTTP-Client schreibt man diese als URL-Parameter oder nutzt URL-Encoding. Für die Entwicklung ist es sinnvoll, eine strukturierte .http-Datei pro Domäne anzulegen: api-products.http, api-customers.http, api-orders.http und api-catalog.http. So findet man den benötigten Request schnell über den Projektbaum von PhpStorm.

Der HTTP-Client zeigt im Response-Bereich nicht nur den Body, sondern auch alle Response-Header und den HTTP-Status. Gerade bei Magento-API-Fehlern sind die Header relevant: Magento sendet im Fall von Validierungsfehlern einen 400-Status mit einem JSON-Body, der den Fehlercode und die Fehlermeldung enthält. Die X-Magento-Cache-Debug-Header zeigen, ob eine Antwort aus dem Varnish-Cache kommt. Diese Informationen direkt neben dem Request zu sehen, beschleunigt das Debugging von API-Integrationen erheblich.

5. GraphQL in PhpStorm einrichten

PhpStorm unterstützt GraphQL nativ seit Version 2023.1. Für optimale Unterstützung installiert man zusätzlich das GraphQL-Plugin aus dem JetBrains Marketplace. Dieses Plugin ermöglicht die Introspection des GraphQL-Schemas direkt aus der IDE: über eine Konfigurationsdatei .graphqlconfig im Projektroot definiert man den GraphQL-Endpoint von Magento. PhpStorm lädt das Schema via Introspection und bietet danach vollständige Autovervollständigung für alle Magento-GraphQL-Types, Queries und Mutations.

Das Magento-GraphQL-Schema ist umfangreich: über zweihundert Types, dutzende Queries und Mutations für Katalog, Warenkorb, Checkout, Customer-Account und CMS. Mit Schema-Introspection navigiert man in PhpStorm von einem Field-Namen direkt zur Type-Definition, sieht alle verfügbaren Fields eines Types und erhält Hinweise auf deprecated Fields. Das ist effizienter als ständig in der Magento-Dokumentation nachzuschlagen.

### .graphqlconfig — Magento GraphQL Schema Introspection
{
  "name": "Magento GraphQL",
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "Dev": {
        "url": "https://magento.local/graphql",
        "headers": {
          "Store": "default",
          "Content-Type": "application/json"
        }
      }
    }
  }
}

### GraphQL — run after .graphqlconfig is set up
POST {{base_url}}/graphql
Content-Type: application/json
Store: https://www.mironsoft.de/

{
  "query": "{ __schema { queryType { name } } }"
}

6. Magento GraphQL-Queries mit Variablen

Das HTTP-Client-Format für GraphQL unterscheidet sich leicht vom REST-Format. Der Body ist ein JSON-Objekt mit dem Schlüssel query für die Query-Zeichenkette und optionalem variables-Objekt. PhpStorm unterstützt alternativ das native GraphQL-Format in .gql-Dateien, die dann über eine spezielle Syntax in der .http-Datei referenziert werden. Für Magento empfiehlt sich das JSON-Format in der .http-Datei, weil Variables und Headers eng zusammengehören und alles in einer Datei bleiben kann.

Magento-GraphQL unterstützt per Store-Header die Multi-Store-Konfiguration. Jeder Request muss den Store-Header mit dem Store-Code senden, andernfalls antwortet Magento mit dem Default-Store. Bei Projekten mit mehreren Store-Views – etwa einem deutschen und einem englischen Store – ist dieser Header kritisch. Im HTTP-Client Environment definiert man store_code als Variable und kann zwischen Stores wechseln, ohne jeden Request einzeln anzupassen.

### GET Product by SKU — Magento GraphQL with variables
POST {{base_url}}/graphql
Content-Type: application/json
Store: https://www.mironsoft.de/

{
  "query": "query GetProduct($sku: String!) { products(filter: { sku: { eq: $sku } }) { items { id name sku price_range { minimum_price { regular_price { value currency } } } description { html } categories { name url_path } media_gallery { url label } } } }",
  "variables": {
    "sku": "MH01"
  }
}

###

### Customer Login — get customer token via GraphQL
POST {{base_url}}/graphql
Content-Type: application/json
Store: https://www.mironsoft.de/

{
  "query": "mutation LoginCustomer($email: String!, $password: String!) { generateCustomerToken(email: $email, password: $password) { token } }",
  "variables": {
    "email": "{{customer_email}}",
    "password": "{{customer_password}}"
  }
}

> {%
  client.global.set(
    "customer_token",
    response.body.data.generateCustomerToken.token
  );
%}

7. Environments für Local, Staging und Production

Die Environment-Trennung ist der wichtigste Qualitätsaspekt beim Arbeiten mit dem HTTP-Client. Eine versehentlich an Production gesendete Mutationsanfrage – etwa das Erstellen eines Test-Produkts oder das Löschen einer Kategorie – kann erheblichen Schaden anrichten. PhpStorm zeigt das aktuell aktive Environment prominent im HTTP-Client-Toolbar-Bereich an. Wer Production-Requests ausführen will, muss das Environment explizit wechseln – eine bewusste Hürde, die Fehler verhindert.

Die http-client.env.json trennt alle URL-abhängigen Werte: Base-URL, Store-Code, API-Version und eventuell unterschiedliche Header-Werte zwischen Stages. Sensible Credentials bleiben in der privaten Datei. In Staging-Umgebungen ist es sinnvoll, den Customer-Token automatisch neu zu holen (über den vordefinierten Token-Request), weil Staging-Datenbanken regelmäßig aus Production-Dumps erneuert werden und alte Tokens ungültig werden. Der Response-Handler des Token-Requests übernimmt das automatisch.

8. Response-Scripting und Assertions

Der Response Handler in PhpStorm HTTP-Client ist JavaScript-basiert und bietet Zugriff auf response.body, response.status und response.headers. Mit client.test("Name", function() {...}) definiert man Assertions, die nach dem Request ausgewertet werden. Schlägt eine Assertion fehl, markiert PhpStorm den Test als rot im Test-Ergebnis-Panel. Das ermöglicht leichtgewichtige Smoke-Tests für API-Endpoints direkt in der IDE.

Für Magento sind typische Assertions: HTTP-Status ist 200, das Response-JSON enthält das erwartete Feld, die Produktpreise sind größer null, der Customer-Token ist ein nicht-leerer String. Diese Tests laufen nach jedem manuellen Request und geben sofort Feedback. Das ist kein Ersatz für ein vollwertiges API-Test-Framework wie REST-assured oder Karate, aber für den Entwicklungsalltag ausreichend, um offensichtliche Regressionen früh zu erkennen.

9. HTTP-Client vs. Postman im Vergleich

Der direkte Vergleich macht die Stärken und Schwächen beider Tools deutlich. Postman hat eine ausgereiftere UI für Collections mit komplexer Ordner-Struktur und bietet Team-Sharing über Cloud-Sync. Der PhpStorm HTTP-Client punktet mit der nativen Repository-Integration und dem Wegfall eines separaten Tools.

Für Teams, die bereits PhpStorm verwenden und ihre API-Requests versionieren wollen, ist der HTTP-Client die überlegene Lösung. Der einzige legitime Grund für Postman bleibt das Teilen von Collections mit Nicht-Entwicklern (Projektmanager, QA ohne IDE) – für diesen Anwendungsfall bietet Postman eine zugänglichere Oberfläche. Alles andere spricht für den integrierten HTTP-Client.

10. Zusammenfassung

Der integrierte HTTP-Client von PhpStorm ist für Magento-2-Entwickler die effizienteste Lösung für API-Tests. Die .http-Dateien leben im Repository und sind für das gesamte Team sofort verfügbar. Environment-Variablen trennen Local, Staging und Production sauber. Response-Handler extrahieren Tokens automatisch und schreiben sie in Session-Variablen. GraphQL-Unterstützung mit Schema-Introspection macht das manuelle Nachschlagen in der Dokumentation weitgehend überflüssig.

Die praktische Empfehlung für Magento-Teams: eine api/-Verzeichnisstruktur im Repository anlegen und nach Domänen trennen – api/products.http, api/customers.http, api/graphql-catalog.http. Die http-client.env.json einchecken, die http-client.private.env.json in die .gitignore. Jeder neue Endpoint bekommt sofort einen Request in der entsprechenden Datei – so entsteht eine lebendige API-Dokumentation, die immer aktuell ist, weil sie direkt aus der Entwicklung stammt.

11. FAQ: PhpStorm HTTP-Client für Magento