Using Apollo Sandbox: Testing Your Local GraphQL API

Previously in this course, we covered Installing Apollo Server: Your GraphQL API Foundation and Defining the TypeDefs for your Apollo Server Project. Now that you have a server running with a basic schema, it's time to interact with it.

Developing GraphQL APIs without a specialized tool is like trying to drive a car while blindfolded. You need a way to send queries, inspect the schema, and view responses in real-time. That is where Apollo Sandbox comes in.

What is Apollo Sandbox?

Apollo Sandbox is a powerful, browser-based IDE designed specifically for GraphQL development. Unlike a standard REST client (like Postman or cURL), Sandbox is "GraphQL-aware." This means it understands your schema, provides auto-completion while you type, and helps you construct valid queries by suggesting available fields.

When you start your Apollo Server in development mode, it automatically serves an instance of Apollo Sandbox at the root URL of your server. It acts as a bridge between your code and your browser, allowing you to iterate on your API without writing a frontend application.

Launching Your Sandbox

Assuming you have your project set up from our previous lessons, ensure your server is running (usually via node index.js or npm start).

1. Open your terminal and confirm your server is listening (check for console logs like "Server ready at http://localhost:4000").
2. Navigate to http://localhost:4000 in your browser.
3. You should see the Apollo Sandbox welcome screen.

If you are prompted to connect, ensure the URL points to your local endpoint (e.g., http://localhost:4000). If everything is configured correctly, the left-hand sidebar will populate with your schema documentation.

Executing Your First Query

Once the Sandbox is open, you will see a central pane for writing your operations. Let's run a test query to ensure your server is communicating with the client.

Copy the following into the operation editor:

GraphQL
query TestConnection {
  # Replace 'hello' with a field from your current project's schema
  hello
}

Click the Play button (the triangle icon). You should see the response appear in the right-hand panel in JSON format.

Why use Sandbox over raw HTTP requests?

Hands-on Exercise

To verify your setup, perform the following steps:

1. Open your typeDefs file and ensure you have at least one field defined under the Query type.
2. Launch your local server.
3. Open Apollo Sandbox and use the auto-complete feature (press Ctrl + Space or Cmd + Space inside the editor) to see if it lists your defined fields.
4. Execute a query for that field and observe the JSON response.

Common Pitfalls

• Server not running: The most common issue is forgetting to start the development server. Sandbox cannot connect to a non-existent port.
• Introspection disabled: If you have followed security best practices like those discussed in GraphQL security: Hardening Schema Exposure Against Introspection, you may have explicitly disabled introspection. If you can't see your documentation, check your server configuration to ensure introspection: true is set for development environments.
• CORS errors: If your browser is hitting a different port or domain, you might encounter Cross-Origin Resource Sharing (CORS) errors. Apollo Server handles this by default, but ensure you haven't restricted origin access too tightly in your production config.

FAQ

Q: Does Apollo Sandbox save my queries? A: Sandbox keeps your current state in the browser's local storage for your convenience during the session, but it is not a persistent database.

Q: Is this tool safe for production? A: Sandbox is for development. In production, you should almost always disable introspection to prevent unauthorized users from mapping out your entire API structure.

Q: Can I use other tools like Insomnia or GraphiQL? A: Absolutely. While we use Apollo Sandbox because it integrates seamlessly with Apollo Server, the underlying GraphQL protocols are standard. Any tool that supports introspection will work.

Recap

In this lesson, we transitioned from writing static schema code to actively testing our API. You now know how to launch Apollo Sandbox, use it to send operational queries, and utilize the built-in IDE features to speed up your development workflow.

Up next: We will dive into Understanding Introspection to see how tools like the Sandbox actually "discover" the shape of your API automatically.