GraphQL Playground

Testing and composing GraphQL queries

Jens Dressler

Founder & CEO

GraphQL is a popular and widely used query language and runtime for APIs. Since its inception, GraphQL has attracted developers for its simplicity and intuitive approach to fetching data from network-based applications.

With GraphQL, one of the critical drivers for developer productivity is the ability to test queries with a GraphQL playground before integrating them into any user-facing product. Luckily there are a whole bunch of GraphQL tools allowing App developers to execute GraphQL queries. Check out The Top 11 GraphQL Tools in 2023 for inspiration.

GraphQL server platforms often have an integrated GraphQL playground to simplify composing and testing queries for a newly published GraphQL API. To give graphapi® customers the best GraphQL playground experience, we integrated GraphiQL version 2.0 with full language support of the latest GraphQL Specification, syntax highlighting, autocompletion, automatic schema reloading, error annotations, and query persistence. Frontend developers can integrate GraphiQL into their web apps or developer portals as a React component.

What is a GraphQL Playground?

A GraphQL Playground works like an integrated development environment. It enables developers to execute queries and analyze the results returned from the GraphQL server. Developers can also use it for creating, updating, or deleting data with GraphQL mutations.

The GraphQL introspection query enables a GraphQL playground to discover the available GraphQL queries, mutations, subscriptions, object types, and object fields. Thus the only thing needed to allow for all the playground magic is the APIs GraphQL endpoint.

There are a couple of essential features a GraphQL playground should provide to remove the guesswork when composing queries:

Syntax highlighting
Auto-completion
Error annotations
Schema reloading
Query Persistence
Query History
GraphQL Variables

Most web-based GraphQL Playground apps use components of GraphiQL under the hood but might add additional features like interactive documentation, support for GraphQL subscriptions, automatic schema reloading, and sharing.

The power of GraphQL queries

One of the differentiating features of GraphQL is that the client defines how the response from a GraphQL server is structured. App developers can familiarize themselves with GraphQL concepts like aliases, fragments, variables, and arguments using a GraphQL playground.

Check our video on GraphQL queries and how to use fragments, aliases, and variables.

Query with variables

The standard for serving GraphQL queries over HTTP most GraphQL clients support looks as follows:

    
{
  "query": "...",
  "operationName": "...",
  "variables": {
    "key": "value"
  }
}

So, to allow developers to copy queries or mutations directly into their frontend code, a GraphQL playground should support defining variables.

Query with fragments

Another powerful language concept of GraphQL is called fragments. A GraphQL fragment is a reusable unit of data that represents a selection of fields on a GraphQL Type:

    
fragment post_fields on Post {
  id
  createdAt
  title
}
query list_posts_with_fragments($limit: Int) {
  posts:listPosts(limit: $limit) {
    items {
      ...post_fields
    }
}

When your GraphQL playground of choice supports defining fragments, it speeds up testing different sets of queries or mutations returning the same type. After all, developers prefer to avoid repeating themselves. However, it is essential to note that the GraphQL client used in your frontend code must also support using fragments. The Relay GraphQL client, for example, provides a `useFragment` hook which makes rendering the data for a GraphQL fragment quite simple.

GraphQL subscriptions

GraphQL Subscriptions enable real-time or reactive features for an application. A client establishes a persistent WebSocket connection to the GraphQL server for retrieving mutation events. For subscriptions to work with GraphiQL, developers must implement a customer fetcher that connects to the real-time endpoint of the GraphQL API.

Some of the more powerful GraphQL IDEs, like the standalone graphql-playground desktop app, which Prisma originally developed, support GraphQL subscriptions without any additional required implementation.

Conclusion

GraphQL's discoverability features allowed the community to build powerful developer tools for GraphQL. During development, a GraphQL playground is a developer's best friend, as it increases productivity significantly. With graphapi, we integrated GraphiQL v2.0, which offers most features described in this article. As soon as an API is published, developers can run queries, write, update, and delete data and have direct access to all generated types and fields of the API via the built-in documentation.

Useful References

Publish an enterprise-scale business app with a no-code platform that developers love.