GraphQL: Using Postman with Examples - Dgraph Blog

[mrjn (Manish R Jain)]

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 can we start Dgraph and get the schema for your GraphQL server using a GraphQL query.

Step 1: Run Dgraph

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.

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 and update the URL to http://localhost:8080/admin.


• Goto 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. As we just started our cluster, 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 http://localhost:8080/admin/schema endpoint. 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.

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.


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 about developing Dgraph Admin API using Postman, we'll do just that.

References

---

This is a companion discussion topic for the original entry at https://dgraph.io/blog/post/graphql-using-postman/

[devguynz (Scott D)]

Thanks, great article!