GraphQL

Zyvra mocks and calls GraphQL services as well as REST and SOAP ones. Everything runs on your computer.

Call a GraphQL service

Choose GraphQL in the New request dialog. A GraphQL request is always a POST of JSON, so it has no method or Params tab. Its Body tab is a query editor that knows GraphQL: it colours the text, shows an error with its line, and has Prettify. When the query has several operations, an operation picker chooses which one runs (it sets the operationName). Variables are JSON below the query, and Fill variables writes a skeleton from the query’s variable definitions.

A new request starts with two checks, status is 200 and no errors, and a reply that carries GraphQL errors shows them in a card instead of leaving you to read the JSON.

The schema is asked for by itself once the address is set, using the request’s own headers and authentication (press Reload after you set them). If the server does not answer introspection, or does not exist yet, Import schema keeps a schema file (SDL or an introspection result) with the request instead.

The Schema panel has a Build tab: a tree of checkboxes. Tick a field and it goes into the query, with the arguments it cannot do without; tick an argument and it becomes a variable, declared and filled with a sample value; untick and it goes again. What is ticked is read from the query, so typing and ticking stay in step. The Operations tab gives a ready query for a root field, and the Types and SDL tabs show the rest.

The query editor completes from the schema: the fields of the type you are in, a field’s arguments, the values of an enum, your variables, type names after on, and @skip and @include. Press Ctrl+Space to ask for it. A field the schema does not have, a missing argument or an undeclared variable is underlined as you type, with the first few listed under the editor. Comments in your query are kept when the Build tab rewrites it.

Import a schema

Choose Import GraphQL on the Mock Services page (or in the API Client’s Import menu), or run zyvra import graphql <file or URL>. The schema can be SDL pasted or uploaded, the result of an introspection query, or a server to ask (with an Authorization header if it wants one). Zyvra lists the queries and mutations with a sample query and sample data for each, and makes:

  • a mock service with an endpoint for each root field you choose, answering with sample data shaped by the schema;
  • an API Client collection with a ready request for each.

When the schema changes, import it again with Update an existing GraphQL service (or collection): new fields are added, and what you wrote is kept.

How a mock answers

A GraphQL mock has one address (POST /graphql) and each root field is an endpoint of its own, with its own scenarios and rules. A field named * answers any field no endpoint names. A call that asks for several fields is answered by the endpoints of all of them.

A scenario holds the value of the field, and Zyvra writes the rest: it wraps the value in data, and trims it to what the query asked for, aliases, fragments, @skip, @include and __typename included. Tick Send the value as written to turn the trimming off. A scenario can answer GraphQL errors instead, with a message and extensions; the field is then null and the error says where.

The service answers introspection from its schema, so a client’s own schema explorer works against it. Switch on Check requests against the schema and a query that does not follow the schema is answered with a GraphQL error that says what is wrong (HTTP 400), shown in Traffic as refused: schema. Subscriptions are refused.

Rules and templates

A rule can look at the call’s arguments (args.id), its variables (variables.id), its operation name and its type. Arguments are read whether the caller wrote them in the query or sent them as variables. In the rule’s name box, a field’s own sample query suggests its args.… and variables.…. In a scenario’s body, {{request.graphql.args.id}}, {{request.graphql.field}}, {{request.graphql.operationName}} and {{request.graphql.variables.id}} copy values of the call into the answer.

One kind at a time

A mock service, a collection and a request are each REST, SOAP or GraphQL, never a mix, and each has an icon that says which. Postman collections that hold only GraphQL calls import as GraphQL collections, a cURL command that posts a query becomes a GraphQL request, and a browser recording (HAR) lists its GraphQL calls by operation and puts them in a GraphQL collection of their own, next to the REST one. You can make a mock from a collection of GraphQL requests, and Save as mock on a reply keeps it as a field.

Not supported: subscriptions, GET queries, persisted queries, file uploads and federation.