GraphQL provides clients with the power and flexibility to selectively request the data they need. Consequently, GraphQL makes it easier to evolve APIs over time.
Altair is a GraphQL API client to explore APIs. It is to GraphQL what Postman is to REST. Altair provides a good alternative to traditional GraphiQL and Playground. It is feature-packed, easy to use, and comes with an inbuilt debugger, making it great for debugging.
In this article, we’ll learn how to debug GraphQL APIs using Altair. So, let’s get started with the prerequisites in the next section.
The following are required to get the most from this article:
While Altair is definitely a feature-packed API client, we’re interested in its debugging features for this article.
In programming, debugging is identifying the root cause of an issue and fixing it. During development, we want to be able to debug faster for any errors happening across the different components of an API. Some debugging strategies used include:
Let’s see how Altair can streamline our debugging methods.
Altair fosters debugging by allowing us to manipulate inputs and inspect the outputs to better understand the relationship between the two.
As an Electron app, Altair comes with an inbuilt developer tool, which in a nutshell is the developer tool of the Chromium browser. That’s because Electron combines the Chromium rendering engine and the Node.js runtime.
The Chromium browser is essentially unbranded Chrome, and both browsers use the Blink rendering engine and the v8 JavaScript engine. Consequently, they give the same support for CSS, HTML, DOM rendering, JavaScript compatibility, functionality, and performance.
When debugging with Altair, we use both the Altair API client and the Altair developer tool.
The Altair client enables us to manipulate inputs and inspect data. Consequently, it allows us to inspect all the pieces of our request and response — specifically our HTTP response and error messages.
And as a result of this, we can:
The Altair developer tools provide us with these useful features:
Let’s learn more about the developer tools in the next section.
We will need a GraphQL project for this; you can use your own or clone the demo project from here.
The project is a simple Node application that resolves our GraphQL query and returns results from mock data:
export default {
users: [
{ id: 1, username: 'JohnDoe', email: '[email protected]', password: '12345', role: 'admin' },
{ id: 2, username: 'JaneDoe', email: '[email protected]', password: '12345', role: 'user' },
{ id: 3, username: 'JoeDoe', email: '[email protected]', password: '12345', role: 'user' }
]
};
The user and users fields are protected, and they both require admin-level permission to access. Only the login query is not protected. Our aim in this article is not to learn how the project was built but to learn how to debug GraphQL APIs using this application.
And we will focus on doing that. Let’s set up the project and start debugging.
Follow these instructions to set up the project:
Learn more →cd into the directory:mkdir <-- project name --> cd <-- project name -->
// clone project git clone https://github.com/lawrenceagles/fastify-graphQL-Altair // install dependencies npm install
npm start
With that work, we get:
> [email protected] start /home/eagles/Work/projects/fga > node --es-module-specifier-resolution=node ./src/index.js {"level":30, "time":1646401128942, "pid":8565, "hostname":"your-pc-model","msg":"Server listening at http://127.0.0.1:4500"}
With this all set up, we’ll learn how to work on these debugging issues: the even source error event, 404 not found, 401 unauthorized, 403 forbidden, and 400 bad request.
We will try to replicate and debug these errors as we learn. Let’s start with 401 unauthorized errors.
A 401 Unauthorized error occurs when a user fails authentication, and this can happen for different reasons:
Let’s replicate and debug this error in our application using the Altair client. Open your Altair client and run the login query using the following code:
query{
login(username: "JaneDoe", password: "12345xxx") {
role
token
}
}
Make sure to add the following URL to Altair to access our server: http://localhost:4000/graphql. Then, open the Altair developer tool with CTRL + SHIFT + I.
When we run the query, we get:
From the image above, we see that Altair gives us useful error alerts that warn us about the URL. Also, we get the famous ERR_CONNECTION_REFUSED Chrome error.
This is because our URL http://localhost:4000/graphql is not correct. Our server runs on port 4500 and we used port 4000 in the URL construct. This is deliberate to produce this error. Since this article is focused on debugging, we will deliberately throw an error for us to debug.
Update your Altair URL to http://localhost:4500/graphql and try again — be sure to clear your console.
Now we get:
This immediately tells us there is an issue with our credentials. We can easily fix that by removing the xxx from the password and trying again.
Now we get:
The 401 unauthenticated error can also be thrown when we query a protected API without providing a valid token. In our application, the users type is protected. Open a new tab in your Altair client and query this type using the code below:
query {
users {
id
username
password
email
role
}
}
Now we get:
Since we generated a token in our previous query, let’s use that and see what we get. We will do this as we learn about the 403 forbidden error.
Let’s learn how to resolve a 403 Forbidden error. To authenticate a user, our API requires we pass a token via the header using x-user as the key.
In the previous example, we failed to query the users type because we were not authenticated. But since we have generated a token in the login example, copy that token and add it to the users query as seen below:
Click Save and run the query again.
Now we get:
The 403 error above tells us that we do not have permission to query the users field. In our application, all users have a role — namely admin or user — and this is used to determine what operation a user can perform. The users type requires an admin role or privilege to query it. Therefore, the server understands our query but refuses to authorize it because we do not have the required permission.
Let’s log in with another user credential — JohnDoe, an admin — and generate another token with a user with an admin role.
Open a new tab in your Altair client and run the code below:
query{
login(username: "JohnDoe", password: "12345") {
role
token
}
}
Now we get:
Finally, use this token to run the users query again. And we get:
The 404 Not Found error is thrown when the server fails to find the resource we query for.
To replicate this error, we would query for a single user using the code below:
query{
user(id: 10) {
username
email
password
role
}
}
Now we get:
And by reviewing the query result from the Altair Results tab, we see that the error message says “Invalid User ID.”
Let’s try the query again with a user that exists. Use the code below:
query{
user(id: 1) {
username
email
password
role
}
}
Now we get:
A 400 Bad Request error is thrown when there is a syntax error in the query and it indicates that the server refuses to process the query because of the error in the client’s request.
GraphQL already provides some level of help through type-checking to prevent this error. And once a query has an incorrect syntax, it is underlined with red squiggles in Altair.
Consider the code below:
query{
user(id: 1, password: "12345") {
username
email
password
role
}
}
In the user query, we only need an id argument, but the above query provides an additional password argument.
Running this query blindly would result in the 400 Bad Request as seen below:
Altair is a great GraphQL API client that is gaining traction. You can get a list of all Altair’s features here.
In this article, we learned how to debug GrapqhQL APIs by using the Altair developer tool, which is the Chromium developer tool.
It is important to note that we only focused on debugging client-side GrapqhQL. GraphQL logic such as our resolvers cannot be debugged on the client-side using Altair as this runs on the server — and in our example app, a Node.js server. So, debugging this server-side GrapqQL could be done with something like VSCode.
I hope you learned enough to give Altair a try in your next GraphQL project.
https://logrocket.com/signup/LogRocket is like a DVR for web and mobile apps, recording literally everything that happens on your site. Instead of guessing why problems happen, you can aggregate and report on problematic GraphQL requests to quickly understand the root cause. In addition, you can track Apollo client state and inspect GraphQL queries' key-value pairs.
LogRocket instruments your app to record baseline performance timings such as page load time, time to first byte, slow network requests, and also logs Redux, NgRx, and Vuex actions/state. Start monitoring for free.Would you be interested in joining LogRocket's developer community?
Join LogRocket’s Content Advisory Board. You’ll help inform the type of content we create and get access to exclusive meetups, social accreditation, and swag.
Sign up now
Build scalable admin dashboards with Filament and Laravel using Form Builder, Notifications, and Actions for clean, interactive panels.
Break down the parts of a URL and explore APIs for working with them in JavaScript, parsing them, building query strings, checking their validity, etc.
In this guide, explore lazy loading and error loading as two techniques for fetching data in React apps.
Deno is a popular JavaScript runtime, and it recently launched version 2.0 with several new features, bug fixes, and improvements […]
One Reply to "Debugging GraphQL with Altair"
Hi Lawrence,
Thanks for the good article. But this github to read the source code described here is no longer available. Please help.
git clone https://github.com/lawrenceagles/fastify-graphQL-Altair
Faith