DHIVA LABS · LEARN

Appearance

GraphQL ​

GraphQL APIs take a query that says exactly which fields you want. ApiWorkbench has a body type for it, with a box for the query, a box for variables, and tools that read the API's schema: an explorer, field suggestions and a prettifier.

Send a GraphQL query ​

This example uses the public Countries API at https://countries.trevorblades.com/. It needs no key.

  1. Open a new request tab and set the method to POST.

    GraphQL servers expect POST. Choosing the GraphQL body type does not change the method for you.

  2. Type the endpoint in the URL field:

    text
    https://countries.trevorblades.com/

  3. Open the Body tab and select GraphQL.

  4. Type the query in the top box:

    graphql
    query Country($code: ID!) {
  country(code: $code) {
    name
    capital
    currency
  }
}

  5. Type the variables in the bottom box, as JSON:

    json
    { "code": "IN" }

  6. Select Send.

The response is JSON with a data field:

json
{
  "data": {
    "country": {
      "name": "India",
      "capital": "New Delhi",
      "currency": "INR"
    }
  }
}

What is sent ​

The query and the variables go out together as one JSON body, with Content-Type: application/json:

json
{
  "query": "query Country($code: ID!) { country(code: $code) { name capital currency } }",
  "variables": { "code": "IN" }
}
  • Leave the variables box empty when the query has no variables. The variables field is then left out.
  • The variables box must hold valid JSON. If it does not, the request stops with GraphQL variables are not valid JSON.
  • {{variables}} from your environment work in both boxes and are filled in before sending. Do not confuse them with GraphQL's own $code variables, which belong to the query.

TIP

A GraphQL server usually answers 200 OK even when the query fails. Look for an errors field in the body. A test with Body contains can check for it.

The GraphQL toolbar ​

Above the query box are three buttons and a schema badge.

ControlWhat it does
Fetch schemaAsks the endpoint for its schema. Reads Refetch once a schema is loaded.
ExplorerOpens the schema explorer
PrettifyRe-indents the query: one field per line, two spaces per level. Comments are kept.
Schema badgeNo schema, or the number of types once a schema is loaded

Fetch the schema ​

A schema lists every query, mutation and type the API offers. ApiWorkbench gets it with the standard introspection query.

  1. Enter the endpoint URL. Set up any headers and auth the API needs.

  2. On the Body tab, with GraphQL selected, select Fetch schema.

The badge changes from No schema to the number of types in the schema.

  • The schema request is a POST to the request's URL, with the request's headers and auth. It shows up in the Console.
  • The schema is kept for that URL until you close the app. Select Refetch after the API changes.
  • If it fails, a message says why. Check the URL and auth, and that introspection is enabled: some production APIs turn it off.
  • Without a URL, the button answers Enter the GraphQL endpoint URL first.

Field suggestions ​

Once a schema is loaded, suggestions appear below the buttons while you type in the query box. They are the fields, or arguments, that fit where the cursor is. Select one to insert it.

For example, with the cursor inside country(code: "IN") { }, the suggestions are the fields of a country: name, capital, currency and the rest.

Browse the schema and insert fields ​

  1. Select Explorer. The Schema explorer opens.

  2. The first page lists Operations (query, mutation, subscription) and every type under Types. Type in Search fields and types to filter.

  3. Select an operation or a type to see its fields, with their types and arguments. Select a field to open the type it returns. The back arrow returns.

  4. Select + on a field to add it to your query.

When you add a field:

  • It is placed in the query under its parent fields, which are added too if they are missing.
  • Its required arguments become GraphQL variables. They are declared on the operation and added to the variables box, ready for you to fill in.
  • A line confirms what was added, for example Added country.name or Added country with variables $code.

Deprecated fields are marked with the reason the schema gives.

Auth and headers ​

GraphQL requests use the same Auth and Headers tabs as any other request. Most GraphQL APIs want a bearer token: set Auth type to Bearer Token. See Authorization.

Subscriptions ​

The GraphQL body type sends one request and reads one response, which suits queries and mutations. The explorer lists subscription fields so you can read them, but the GraphQL body type does not open the streaming connection a subscription needs. A server that offers subscriptions over WebSocket can be reached from a WebSocket tab, where you write the protocol messages yourself.

Next steps ​