GraphQL: Using Postman with Examples

Update: On April 16th 2021, Slash GraphQL was officially renamed Dgraph Cloud. All other information below still applies.

Postman is one of the most popular REST API clients. Since v7.2, it also supports GraphQL APIs. In this blog post, we will look at how you can use Postman to make GraphQL requests. We will also look at some of the advantages of doing so. Please note that the screenshots used in this blog post are for Postman v7.2.5.

How to use Postman with your GraphQL API

First, let’s see how we can start Dgraph locally and get the schema for your GraphQL server using a GraphQL query. We’ll also go through the necessary steps to achieve the same thing when working with a remote GraphQL backend deployed with Slash GraphQL.

Step 1: Setting up a GraphQL backend

You can set up a local Dgraph cluster by using the Docker image:

docker run -it -p 8080:8080 -p 9080:9080 -p 8000:8000 dgraph/standalone:latest

Note - You can also try the dgraph/standalone:master image to try out experimental features that haven’t been released yet.

If you want to have a fully-managed, functional and production-ready GraphQL backend that’s serving a GraphQL API remotely, then Slash GraphQL is what you want. Go over here to sign up if you haven’t done so and start for free. As you’ll soon see, just like your local Dgraph instance, you can interact with your remote GraphQL API just from your schema and perform requests using Postman.

After signing up, you’ll be greeted with a dashboard.

The dashboard is empty for now since there’s no backend running. Let’s give it some colors and spin one up. Click on “Launch a Backend”.

Fill in the name and click on “Launch”; your backend will be ready in no time.

After deployment, your dashboard will show some information, including the URL of your server. Note this down—it’s where all your requests would go.

Step 2: Make a GraphQL request

A GraphQL request is just an HTTP request. This is how you can make a request to get the Dgraph GraphQL schema.

• Generate a new request by clicking on the + icon.

• Choose POST as the request method. For your local Dgraph instance, update the URL to http://localhost:8080/admin. For the remote backend you just deployed, use the URL from your dashboard with the admin endpoint. In my case it’s https://fretful-lumber.us-west-2.aws.cloud.dgraph.io/admin.

• Go to the Body tab and choose the GraphQL radio box.

• Enter the following GraphQL query in the Query box.

query {
    getGQLSchema {
        schema
    }
}

That’s it! Now you can hit the Send button and get the GraphQL schema that is being served by your Dgraph cluster. But since both the local and remote APIs don’t yet have a schema to serve, you would get a null schema back. In the next part, we’ll see how can we post a new schema to our cluster and execute some queries and mutations based on that.

Benefits of using Postman with GraphQL queries

Now that we have had a look at how GraphQL queries work in Postman, we’ll also take a look at some other features like GraphQL variables, Postman environment variables, query auto-completion. To see these features, we’ll use the Dgraph server that should be already running from Step 1 above. With Dgraph you can turn a GraphQL schema into a running GraphQL API in just two steps. We’ll use the example of building a GraphQL API for a TODO app for this blog post. You can refer to our docs site for a deeper dive into this example.

As an initial step, we’ll post the following GraphQL schema for our application to both our local and remote endpoints. The endpoint to use is admin/schema.

So for the local instance, the URL will be: http://localhost:8080/admin/schema; and for the remote one: https://fretful-lumber.us-west-2.aws.cloud.dgraph.io/admin/schema.

Choose the Body type as raw as shown in the image below.

type Task {
    id: ID!
    title: String!
    completed: Boolean!
    user: User!
}

type User {
    username: String! @id
    name: String
    tasks: [Task] @hasInverse(field: user)
}

In the schema above, we have a title and a completed field in the Task type. Then the User type has a username (unique identifier), name and the tasks. So each user can have many tasks. We have added a @hasInverse directive on tasks to be able to find the user to whom a task belongs to.

You can add this schema to your remote backend from your Slash GraphQL account dashboard too.

From your dashboard, click on “Schema” on the left sidebar. In the new window paste in the schema and click “Deploy”.

That’s it! You now have two APIs ready serving the above schema that are ready to accept GraphQL requests.

Query autocompletion

Currently, Postman doesn’t use the schema introspection feature to automatically pull your GraphQL schema. There is an open issue for it and we hope for it to be supported soon because the following manual steps are done automatically by other GraphQL IDE tools. The GraphQL schema has to be added to your Postman API schemas for you to be able to take advantage of the Query Autocompletion features for your GraphQL API. Follow these steps to upload the generated GraphQL schema to Postman.

• Query the Dgraph instance to get the generated schema. Before running the query, go over to the Tests tab and add these lines below.

var jsonData = pm.response.json();
pm.globals.set("schema", jsonData.data.getGQLSchema.generatedSchema);

This would parse the JSON response from the server, extract the generated schema and store it in a global variable inside the Postman app so that we can use it later.

Once you have added the test script, you can head over the Body tab and make the request like shown in the image below.

query {
    getGQLSchema {
        generatedSchema
    }
}

• Go to the APIs tab in Postman and click on + New API

• In the dialog that appears, enter the API name as TODO app, Version as 1.0.0, Schema type as GraphQL, Schema format as GraphQL SDL and click Create API.

• Now we’ll copy over the schema from the environment variable lookup. Click on the environment variable lookup icon.

• Click on edit next to Globals and then click on the Current Value box for schema variable. Select the whole value and copy it as shown in the image.

• Finally, close the environment variable modal by clicking Cancel and then paste the copied value into the API Define tab. Then click Save.

• Once you have uploaded the schema to Postman API schemas, you can get back to making requests. Before you do so, select the TODO app schema from the dropdown as shown below. If the schema isn’t available, then hit the refresh button on the right and it should appear. Loading the schema like this in Postman is not as simple as loading the schema in some other tools, but it still works nicely.

With all of the above setup, now when you type in a GraphQL query, you should see support for auto-completion of your queries. Let’s try that out with Dgraph’s GraphQL endpoint that’s being served at http://localhost:8080/graphql and the remote backend at https://fretful-lumber.us-west-2.aws.cloud.dgraph.io/cloud.

GraphQL variables

GraphQL variables allow the user to use the same query/mutation but with different inputs. Now we’ll see an example of how to use them in Postman. For this example, first we’ll add a user Alice and some Todo’s to our application and then query them. Run the following mutation first.

mutation {
  addUser(input: [
    {
      username: "[email protected]",
      name: "Alice",
      tasks: [
        {
          title: "Avoid touching your face",
          completed: false,
        },
        {
          title: "Stay safe",
          completed: false
        },
        {
          title: "Avoid crowd",
          completed: true,
        },
        {
          title: "Wash your hands often",
          completed: true
        }
      ]
    }
  ]) {
    user {
      username
      name
      tasks {
        id
        title
      }
    }
  }
}

Just like with the query request before, click + to create a new request and send the mutation to Dgraph.

Once the mutation returns successfully, we can run a GraphQL query to fetch alice and her tasks. In the request below, user is a GraphQL variable with a value [email protected]. Its value is specified in the GraphQL variables tab as shown in the diagram.

query($user: String!) {
  queryUser(filter: { username: {eq: $user}}) {
    username
    tasks {
        title
        completed
    }
  }
}

Collections

Even though GraphQL APIs are self-documenting, having examples of common patterns of using the API can be very useful. With Postman, you can create a collection that is a way of grouping your requests. This collection can then be shared with your team which provides a convenient and easy way for the team to try out requests without “having to worry about the syntax”.

Collections along with environment variables make it easy to develop, test and monitor your API. For example, the URL for your requests can be dynamically filled in from an environment variable and you can have different environments for your development, staging and production clusters. You can also dynamically update these environment variables based on the response of a request.

As an example, you administer your Dgraph instance using GraphQL, and thus use GraphQL to perform operations like backup, restore and setting access control. These operations require you to log in as an administrator, record the access token returned from login, and pass that access token back in when you perform operations. This is a perfect use case for Postman. By using collections and environment variables you can automate the recording and passing of the access token.

In the next blog, we show how you can perform those admin operations on your Slash GraphQL backend using Postman collections.

Conclusion

As we’ve seen in this article, it’s easy to get started with a GraphQL application using Dgraph and Slash GraphQL; you can start interacting with your API and collaborating right away with tools like Postman. Slash GraphQL offers a production-ready managed backend ready for your application from just a GraphQL schema. When all the hassles of creating a performant API from the ground-up on your own are taken care of by our platform, you can just focus on building your application. So sign up now if you haven’t done so already and start bringing those creative ideas to reality.

In case you need a head start, Dgraph Learn has the resources to get you going with developing real-world applications (like a message board app) using GraphQL, covering from basics to advanced topics of the whole process. It’s completely free and contains many information to make you confident in GraphQL application development, using your favourite frontend frameworks like React and Vue.

Below are some resources that you might find helpful in your learning journey:

• Dgraph GraphQL docs
• Slash GraphQL docs
• Postman GraphQL docs