TullyAPI

Fast, simple API testing tool. Now with environment variables and GraphQL!

Now with more bug fixes.

Back to App

What is GraphQL? A Guide for API Developers

• 8 min read

If you've worked with APIs, you've likely encountered REST—the standard approach for decades. But there's a new player revolutionizing how we build and consume APIs: GraphQL. Developed by Facebook in 2012 and open-sourced in 2015, GraphQL solves some of REST's most frustrating limitations. In this guide, you'll learn what GraphQL is, how it compares to REST, and how to test GraphQL APIs using TullyAPI.

What is GraphQL?

GraphQL is a query language for APIs and a runtime for executing those queries. Unlike REST, where the server defines what data each endpoint returns, GraphQL lets clients specify exactly what data they need in a single request.

Created by Facebook in 2012 to solve data-fetching challenges in their mobile apps, GraphQL was open-sourced in 2015 and has since been adopted by companies like GitHub, Shopify, Twitter, and Netflix.

Key Characteristics

  • Single Endpoint: All requests go to one URL (e.g., /graphql), unlike REST's multiple endpoints
  • Client-Specified Queries: The client decides exactly what data to fetch
  • Strongly Typed Schema: The API defines a schema with types, fields, and relationships
  • No Over-fetching or Under-fetching: Get exactly what you need, nothing more, nothing less
  • Hierarchical Structure: Queries mirror the shape of the data they return

How GraphQL Works

In GraphQL, you send a POST request to a single endpoint (usually /graphql) with a query that describes the data you want. The server responds with JSON that matches the exact structure of your query.

Queries: Fetching Data

A GraphQL query looks like this:

Query:

query {
  user(id: "123") {
    id
    name
    email
    posts {
      title
      publishedAt
    }
  }
}

Response:
{
  "data": {
    "user": {
      "id": "123",
      "name": "John Doe",
      "email": "[email protected]",
      "posts": [
        { "title": "My First Post", "publishedAt": "2025-01-15" },
        { "title": "GraphQL Basics", "publishedAt": "2025-01-20" }
      ]
    }
  }
}

Notice how the response structure exactly matches the query structure. You asked for id, name, email, and nested posts with title and publishedAt—and that's exactly what you got.

Mutations: Modifying Data

To create, update, or delete data, you use mutations:

Mutation:

mutation {
  createPost(title: "New Post", content: "Hello World") {
    id
    title
    createdAt
  }
}

Response:
{
  "data": {
    "createPost": {
      "id": "456",
      "title": "New Post",
      "createdAt": "2025-01-31T10:00:00Z"
    }
  }
}

Variables in GraphQL

Instead of hardcoding values in queries, you can use variables for dynamic, reusable queries:

Query with Variables:

query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
  }
}

Variables (JSON):
{
  "userId": "123"
}

This makes queries reusable—just change the variables, not the query itself.

GraphQL vs REST

Let's compare GraphQL and REST across key dimensions:

1. Over-fetching and Under-fetching

REST Problem: You often fetch more data than you need (over-fetching) or need multiple requests to get all required data (under-fetching).

REST Example (Over-fetching):

GET /users/123

Response: { id, name, email, phone, address, bio, avatar, createdAt, lastLogin, ... }

You only needed name and email, but got everything.

REST Example (Under-fetching):

GET /users/123 → Get user
GET /users/123/posts → Get user's posts
GET /users/123/followers → Get user's followers

Three separate requests to build one view.

GraphQL Solution: Request exactly what you need in one query:

query {
  user(id: "123") {
    name
    email
    posts { title }
    followers { name }
  }
}

2. Endpoints

REST: Multiple endpoints (/users, /posts, /comments, etc.)
GraphQL: Single endpoint (/graphql)

This simplifies API architecture and makes it easier to understand what's available—just look at the schema.

3. Versioning

REST: Often requires versioned endpoints (/v1/users, /v2/users)
GraphQL: No versioning needed—you can deprecate fields without breaking existing queries

4. Comparison Table

Feature REST GraphQL
Endpoints Multiple (/users, /posts) Single (/graphql)
Data Fetching Server defines response Client specifies needs
Over-fetching Common Eliminated
Under-fetching Requires multiple requests Single request
Versioning Required (/v1, /v2) Not needed (field deprecation)
Type System Not built-in Strongly typed schema
Learning Curve Low Moderate
Caching HTTP caching (easy) Requires custom logic

How to Test GraphQL APIs in TullyAPI

TullyAPI now has native GraphQL support, making it easy to test GraphQL APIs with a dedicated interface for queries and variables.

Step 1: Switch to GraphQL Mode

  1. Create or select an endpoint in TullyAPI
  2. Set the HTTP method to POST (GraphQL uses POST requests)
  3. Go to the Body tab
  4. In the "Body Type" dropdown, select GraphQL

You'll now see two text areas: one for your GraphQL query and one for variables.

Step 2: Enter Your GraphQL Endpoint

In the URL field, enter the GraphQL endpoint. For most GraphQL APIs, this is:

  • https://api.example.com/graphql
  • https://example.com/api/graphql

Step 3: Write Your Query

In the GraphQL Query field, write your query:

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

Step 4: Add Variables (Optional)

If your query uses variables, define them in the GraphQL Variables field as JSON:

{
  "id": "123"
}

Step 5: Use Environment Variables

You can combine GraphQL with TullyAPI's environment variables feature for even more power:

URL: {{BASE_URL}}/graphql

Headers:
Authorization: Bearer {{API_TOKEN}}

Query:
query GetUser($id: ID!) {
  user(id: $id) { id name email }
}

Variables:
{
  "id": "{{USER_ID}}"
}

Now you can switch between Development and Production environments, and your GraphQL queries automatically adapt.

Step 6: Send the Request

Click Send Request. TullyAPI automatically formats your query and variables into the correct GraphQL request format:

POST /graphql
Content-Type: application/json

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

Popular GraphQL APIs to Try

Ready to test your GraphQL skills? Here are some public GraphQL APIs you can experiment with:

GitHub GraphQL API

Endpoint: https://api.github.com/graphql
Requires: Personal access token
Try: Query repositories, issues, pull requests, users

SpaceX GraphQL API

Endpoint: https://spacex-production.up.railway.app/
Requires: No authentication
Try: Query launches, rockets, crew members, missions

GraphQL Pokemon API

Endpoint: https://graphql-pokemon2.vercel.app/
Requires: No authentication
Try: Query Pokémon, types, abilities, evolutions

Example: Querying SpaceX API

URL: https://spacex-production.up.railway.app/
Method: POST

Query:
query {
  launches(limit: 5) {
    mission_name
    launch_date_local
    launch_success
    rocket {
      rocket_name
    }
  }
}

This query fetches the 5 most recent SpaceX launches with mission names, dates, success status, and rocket names—all in one request!

When to Use GraphQL vs REST

Use GraphQL When:

  • You need flexible, client-driven queries
  • Mobile apps need to minimize data transfer
  • You're aggregating data from multiple sources
  • Rapid iteration requires frequent API changes
  • You want a strongly typed API with auto-generated documentation

Use REST When:

  • You need HTTP caching (GET requests)
  • Simple CRUD operations are sufficient
  • File uploads/downloads are primary use case
  • Team is unfamiliar with GraphQL
  • Existing REST infrastructure is well-established

Start Testing GraphQL APIs

Try TullyAPI's native GraphQL support to test queries, mutations, and variables with ease. Free, privacy-first, and no installation required.

Launch TullyAPI →

Key Takeaways

  • GraphQL is a query language that lets clients specify exactly what data they need
  • Single endpoint (/graphql) handles all requests, unlike REST's multiple endpoints
  • No over-fetching or under-fetching—get exactly what you request, nothing more
  • Strongly typed schema provides clear API contracts and self-documentation
  • Use variables to make queries reusable and dynamic
  • TullyAPI supports GraphQL natively with dedicated UI for queries and variables
  • Combine with environment variables for seamless testing across environments

Conclusion

GraphQL is transforming how developers build and consume APIs. By giving clients control over data fetching, eliminating over-fetching, and providing a strongly typed schema, GraphQL solves many of REST's most frustrating limitations. Whether you're building a new API or consuming existing GraphQL endpoints, understanding GraphQL is becoming essential for modern developers.

With TullyAPI's native GraphQL support, you can start testing GraphQL APIs immediately—no complex setup, no privacy concerns, and completely free. Combine it with environment variables to create a powerful, flexible API testing workflow. Try it today and experience the future of API development.