Test Magento GraphQL & REST Endpoints with the PhpStorm HTTP Client

1. Why the PhpStorm HTTP client replaces Postman

The built-in HTTP client in PhpStorm is not a stopgap, it is a full-featured API testing tool. The decisive argument for Magento developers: the .http files in which requests are defined are plain text files, which means they live in the repository. That means the whole team uses the same requests, new endpoints are versioned immediately, and reviews can happen through Git diffs, instead of screenshots from Postman collections that nobody else ever sees.

Another advantage is direct access to environment variables without the detour through an external tool. When the auth token from a preceding request is automatically carried over into the next one, there is no need to manually copy it out of the response window. This matters a lot with Magento APIs, where a customer token first has to be requested via /V1/integration/customer/token and then sent along in the Authorization header on every subsequent request.

The PhpStorm HTTP client supports HTTP/1.1, HTTP/2, GraphQL, WebSocket, and gRPC. For Magento 2 the relevant ones are mainly REST and GraphQL. The IDE shows responses with syntax highlighting, offers JSON path search, and can automatically evaluate responses with JavaScript-based test scripts. All of this with no installation, no account, and no cloud sync, which is a substantial advantage over tools that store data on someone else's servers.

2. .http files: basic structure and syntax

An .http file contains one or more requests, separated by three hash marks (###). Each request consists of a line with the HTTP method and the URL, optional header lines, and an optional body after a blank line. PhpStorm recognizes .http and .rest files automatically and provides play buttons in the editor for running requests directly. The result appears in a split response pane to the right or below, with JSON formatting and navigation through nested structures.

Variables are referenced in double curly braces: {{base_url}}. These variables are defined in a separate http-client.env.json file and grouped by environment (dev, staging, prod). Sensitive values such as passwords and tokens go into an http-client.private.env.json file, which is entered in .gitignore. That way the file structure is versioned without any credentials ending up in the repository.

### 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: authentication and token management

Magento 2 REST APIs distinguish between public endpoints that need no token, customer endpoints that use a customer token, and admin endpoints that use an admin integration token. For development you mainly need the admin token. It is requested via POST /rest/V1/integration/admin/token with username and password in the JSON body. The response is a plain string, which is then sent along as a bearer token in the Authorization header.

The scripting feature of the PhpStorm HTTP client lets you automatically write the token from the response into an environment variable. In the Response Handler block beneath the request you define JavaScript code that runs after the request completes. That way you run the token request once, and every subsequent request in the same session automatically uses the extracted token, with no manual copying involved.

### POST Admin Token - run this first, token stored automatically
POST {{base_url}}/rest/{{store_code}}/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/{{store_code}}/V1/products?searchCriteria[pageSize]=5
Authorization: Bearer {{admin_token}}
Accept: application/json

4. Querying REST endpoints systematically

The Magento 2 REST API follows the search-criteria pattern: every collection endpoint accepts filter groups, sort options, and pagination parameters as query parameters. In the HTTP client you write these as URL parameters or use URL encoding. For development it makes sense to set up one structured .http file per domain: api-products.http, api-customers.http, api-orders.http, and api-catalog.http. That way you can quickly find the request you need through the PhpStorm project tree.

The HTTP client's response area shows not only the body but also all response headers and the HTTP status. Headers matter especially for Magento API errors: on validation errors Magento sends a 400 status with a JSON body that contains the error code and the error message. The X-Magento-Cache-Debug headers show whether a response came from the Varnish cache. Seeing this information right next to the request considerably speeds up debugging API integrations.

5. Setting up GraphQL in PhpStorm

PhpStorm has supported GraphQL natively since version 2023.1. For the best support, additionally install the GraphQL plugin from the JetBrains Marketplace. This plugin enables schema introspection directly from the IDE: through a configuration file .graphqlconfig in the project root you define Magento's GraphQL endpoint. PhpStorm loads the schema via introspection and then offers full autocompletion for all Magento GraphQL types, queries, and mutations.

The Magento GraphQL schema is extensive: over two hundred types, and dozens of queries and mutations for catalog, cart, checkout, customer account, and CMS. With schema introspection you can navigate in PhpStorm from a field name straight to the type definition, see all available fields of a type, and get hints about deprecated fields. That is far more efficient than constantly looking things up in the Magento documentation.

### .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: {{store_code}}

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

6. Magento GraphQL queries with variables

The HTTP client format for GraphQL differs slightly from the REST format. The body is a JSON object with a query key for the query string and an optional variables object. As an alternative, PhpStorm supports the native GraphQL format in .gql files, which are then referenced from the .http file via a special syntax. For Magento, the JSON format inside the .http file is recommended, because variables and headers belong closely together and everything can stay in one file.

Magento GraphQL uses a store header to support multi-store configuration. Every request must send the Store header with the store code, otherwise Magento responds with the default store. On projects with multiple store views, for example a German and an English store, this header is critical. In the HTTP client environment you define store_code as a variable and can switch between stores without adjusting every request individually.

### GET Product by SKU - Magento GraphQL with variables
POST {{base_url}}/graphql
Content-Type: application/json
Store: {{store_code}}

{
  "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: {{store_code}}

{
  "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 for local, staging, and production

Separating environments is the most important quality aspect of working with the HTTP client. A mutation request accidentally sent to production, for example creating a test product or deleting a category, can cause considerable damage. PhpStorm displays the currently active environment prominently in the HTTP client toolbar area. Anyone wanting to run production requests has to explicitly switch environments first, a deliberate hurdle that prevents mistakes.

The http-client.env.json file separates all URL-dependent values: base URL, store code, API version, and possibly different header values between stages. Sensitive credentials stay in the private file. In staging environments it makes sense to automatically fetch a fresh customer token (via the predefined token request), because staging databases are regularly refreshed from production dumps and old tokens go stale. The token request's response handler takes care of that automatically.

8. Response scripting and assertions

The Response Handler in the PhpStorm HTTP client is JavaScript-based and gives you access to response.body, response.status, and response.headers. With client.test("Name", function() {...}) you define assertions that are evaluated after the request completes. If an assertion fails, PhpStorm marks the test as red in the test results panel. That enables lightweight smoke tests for API endpoints directly in the IDE.

Typical assertions for Magento include: the HTTP status is 200, the response JSON contains the expected field, product prices are greater than zero, and the customer token is a non-empty string. These tests run after every manual request and give immediate feedback. This is not a replacement for a full API test framework like REST-assured or Karate, but it is enough for everyday development to catch obvious regressions early.

9. HTTP client vs. Postman compared

A direct comparison makes the strengths and weaknesses of both tools clear. Postman has a more mature UI for collections with a complex folder structure and offers team sharing via cloud sync. The PhpStorm HTTP client scores with native repository integration and doing away with a separate tool.

For teams that already use PhpStorm and want to version their API requests, the HTTP client is the superior solution. The only legitimate reason to stick with Postman remains sharing collections with non-developers (project managers, QA without an IDE), for that use case Postman offers a more approachable interface. For everything else the built-in HTTP client is the better choice.

10. Summary

The built-in HTTP client in PhpStorm is the most efficient solution for API testing for Magento 2 developers. The .http files live in the repository and are immediately available to the whole team. Environment variables cleanly separate local, staging, and production. Response handlers extract tokens automatically and write them into session variables. GraphQL support with schema introspection makes manually looking things up in the documentation largely unnecessary.

The practical recommendation for Magento teams: set up an api/ directory structure in the repository and split it by domain, api/products.http, api/customers.http, api/graphql-catalog.http. Check in http-client.env.json, put http-client.private.env.json in .gitignore. Every new endpoint immediately gets a request in the appropriate file, and that is how a living API documentation emerges, one that is always current because it comes straight out of the development process.

11. FAQ: PhpStorm HTTP Client for Magento