Testing GraphQL Services

Aethrix Studio imports GraphQL schemas and lets you test queries, mutations, and subscriptions. Queries and mutations travel as an HTTP POST whose body is the standard envelope:

{
  "query": "…the GraphQL document…",
  "operationName": "…",
  "variables": { "…": "…" }
}

The query and operationName fields are generated automatically when you import the schema and are read-only — you only edit the variables object.

A subscription is different by nature: it is not a single request and reply but a stream of events, so it runs over a WebSocket connection that speaks the graphql-transport-ws subprotocol instead of HTTP POST. Aethrix generates subscription operations like every other kind and drives that stream for you — see Subscribing to Events.

When to use this

Use the GraphQL workflow when you have a GraphQL endpoint (single /graphql URL) and want to exercise specific operations with typed input variables, rather than hand-crafting raw HTTP bodies or keeping a separate query file in sync with the schema.

Importing a GraphQL Schema

1. Click Import API in the API Playground toolbar.
2. In Service Type, select GraphQL - Schema Definition Language (SDL).
3. In Service Description, provide one of:
   • A local schema file path (.graphql or .sdl).
   • A URL to an SDL file.
   • A live GraphQL endpoint URL — Aethrix runs the standard introspection query, converts the result to SDL, and imports it.
4. Step through Authentication (only if the endpoint is protected) and Application & Service Name, then click Import.
5. Aethrix analyzes the SDL, compiles typed C# DTOs for each operation's variables, and installs the service as an extension package.

remarque

For a live endpoint, Aethrix performs the introspection query (__schema { queryType / mutationType / … }) and converts the JSON result to SDL before compiling. You do not need to host a separate SDL file.

Service Tree Organization

After import, operations appear in the service tree:

• Application — the name you assigned during import.
• Service — the GraphQL service node.
• Queries — each field of the schema's query type (e.g. users, user(id:)).
• Mutations — each field of the mutation type (e.g. createUser, deleteUser).
• Subscriptions — each field of the subscription type (e.g. messageAdded). A live subscription marks its node with a badge in the tree.

Composing a Request

Select a query or mutation operation from the service tree to open the request editor. Because GraphQL is transported over HTTP, the editor uses the same tabbed layout as REST:

• Request tab — edit the variables object. Use the View Mode selector to switch between Dual View (tree + text), Tree View, Text Only, and HTTP (which shows the full {"query":"…","operationName":"…","variables":{…}} wire body).
• Authentication tab — configure auth (see below).
• Headers tab — add custom HTTP headers.
• Options tab — HTTP options such as Content Type and Accept.

The query document and operationName are filled in from the imported schema and are not editable here; only the variables object is yours to change. Fields are pre-populated with schema defaults when available.

Subscription operations show a different Options tab — see Subscribing to Events; the Authentication and Headers tabs do not apply to them.

Example

For a user(id: ID!) query, the variables object is simply:

{ "id": "123" }

In HTTP view the editor displays the complete request body that will be sent:

{
  "query": "query GetUser($id: ID!) { user(id: $id) { id name email } }",
  "operationName": "GetUser",
  "variables": { "id": "123" }
}

Authentication

GraphQL requests use the same authentication mechanisms as REST. Configure them in the Authentication tab. Most GraphQL APIs use:

• Bearer Token — sent in the Authorization header.
• None — for public APIs.

Sending the Request

1. Select a GraphQL operation from the service tree.
2. Edit the variables object in the Request tab (switch to the HTTP view to confirm the full body if needed).
3. Click Send in the toolbar.

Response Inspection

GraphQL responses are returned as JSON and shown in the response panel:

• JSON body — the data / errors envelope returned by the server. GraphQL protocol errors appear under errors and are surfaced as deserialization warnings.
• Tree view — navigate the response structure hierarchically.
• JSON Path evaluation — right-click a value and use Copy JsonPath (or Show JsonPath) to capture its path for assertions.

Subscribing to Events

A subscription delivers an event every time the server pushes one. The quickest flow:

1. Select a subscription operation in the service tree.
2. Edit the variables object, then click Send.
3. The editor switches to the event panel: each event the server pushes becomes a row (the wire shape, {"data": …}, plus errors when the server reports some), and clicking a row shows its parsed object in the inspector, where JSON Path and the object tree work like on a query response.
4. Click Stop to end the subscription.

The Subscription Options

Subscription operations carry their transport settings in the Options tab, in a Subscription (WebSocket) section:

• WebSocket URL — prefilled from the operation's endpoint (http→ws, https→wss). Edit it when the WebSocket endpoint is mounted somewhere other than the HTTP endpoint.
• Connection payload — a JSON object sent with the connection handshake (connection_init), typically where tokens live. Leave empty for none.

These are per-send settings and are never saved into the operation. The Authentication and Headers tabs do not apply to a subscription.

Keeping a Subscription While You Test

A subscription does not end when you navigate away. Select a different operation — even a mutation of the same service — and its editor is fully usable while the subscription keeps receiving events. The editor's toolbar shows a live pill with the number of running streams and a Stop all button, and the service tree marks each node whose subscription is still live.

Selecting the subscription operation again re-attaches the panel to the running stream, including every event that arrived while you were elsewhere. Send a new subscription from the same node and the previous one is stopped first — one stream per node; different nodes stream in parallel. Deleting a saved variant stops its stream; a protocol error, a server close, or the server's error frame also end it, with the reason shown in the panel.

Service Simulation

Aethrix's simulated HTTP Server answers subscriptions on the same port and URL as everything else: a client that upgrades the connection with the graphql-transport-ws subprotocol reaches the WebSocket plane, while ordinary POST requests keep taking the HTTP plane.

• Dispatch — inside a connection, a subscribe frame selects the operation by its operationName; when the frame names none, the operation is found by its query document (differences in whitespace and formatting are ignored). Two subscription operations with identical documents are refused with an error naming both. An unmatched subscribe is answered with an error frame and the connection stays open.
• Responses — the configured saved responses and their conditions apply, with the subscribe frame as the request being matched. A response with Streaming Frames pushes each frame's value as an event at the configured delays; a response without frames answers a single event carrying the response body as data.
• Faults — declared and runtime faults apply like on HTTP, and the hit appears in the simulator's history.
• POST of a subscription document — the HTTP plane answers "no service running": subscriptions are reachable only over the WebSocket plane.

See Service Simulation Overview for details on configuring responses and conditions.

Limitations

For every GraphQL construct that Aethrix degrades or rejects — with an example, what you see in Studio, and how severe it is — see Import Diagnostics — Unsupported structures & fallbacks (GraphQL tab). This is the single, exclusive reference.

• File uploads — multipart GraphQL uploads are not supported.
• Batching — batched GraphQL requests are not supported.

See Also

• Importing API Specifications
• Testing REST Services
• Authentication Guide