With the most recent release of its namesake product, Postman is now capable of working with GraphQL-based APIs. ProgrammableWeb decided to take a closer look by reviewing the new feature.
Postman is a utility that allows developers to execute HTTP requests against a given URL. Combined with its graphical user interface, this core capability makes it an indispensable tool for making, saving, chaining and replaying ad hoc calls to HTTP (Web) based APIs. Postman was originally released as an extension to the Chrome browser but is now deployed as a standalone application.
The latest version of Postman includes a beta feature that allows developers to execute queries and mutations written in GQL, (GraphQL query language), directly against a GraphQL API (for a detailed explanation of what GraphQL is and how it works, be sure to read ProgrammableWeb'ss comprehensive Guide to GraphQL).
In this article I'm going to show you how to execute a simple GraphQL query against a GraphQL API using the new Postman feature. I'm also going to show you how to use Postman to authenticate to a GraphQL API using Postman, to query variables and finally how to execute a mutation against a GraphQL API endpoint.
The code I'm going to use to show examples of running GraphQL queries under Postman is from ProgrammableWeb's interactive GraphQL tutorial found here. The interactive tutorials have a working instance of a GraphQL API that's used to demonstrate the basics of the technology. You are welcome to use a running instance of the tutorial code to experiment with using GraphQL under Postman.
Setting Up Postman to Run GraphQL Queries
As mentioned previously, Postman is a standalone utility that allows developers to execute HTTP requests against the various resources and endpoints of an API. You can download Postman by going to its download page here.
Once installed, you'll be offered a features review dialog. Feel free to review what interests you. Otherwise you'll be brought to the main Postman GUI. You'll configure your GraphQL queries and mutations using this GUI. (See Figure 1 below)
Figure 1: Postman's The query configuration screen
All queries and mutations in GraphQL are executed using HTTP's POST method (also known as an HTTP "verb"). This is an important fact to remember. Thus, when configuring a GraphQL query using Postman you will need to select POST from HTTP method dropdown shown above in Figure 1 at callout (1). Next you'll enter the URL of the GraphQL API you're working with, as shown above at callout (2). You can also use Postman to work with GraphQL APIs that are running on you local machine under localhost.
There are two ways to furnish security credentials to a GraphQL-based API through Postman. The first way is to select the Authorization tab from within the Postman query pane and select an authorization type from the resulting drop down. In the example shown above at callout (3), the selected authorization type is Bearer Token. As a result of selecting Bearer Token, a pane appears into which you enter the authorization token as shown above in Figure 1, callout (4). The authorization token that is entered into the token textbox will be injected into the POST request when the request is executed.
The second way to add authorization credentials to a GraphQL request is to enter the information directly as headers in the HTTP request. If you prefer this approach, select the Headers tab and then add the header key and associated value into that dialog, as shown above in callout (3a).
Executing a Simple Query
Once you have Postman configured to POST a request, you can add a GraphQL query or mutation. The new GraphQL beta feature in Postman allows you to declare queries in GraphQL Query Language (GQL). GQL is similar to JSON, but has some differences. For example, you don't use commas to delimit fields. The details of GQL are discussed in ProgrammableWeb's article GraphQL APIs for Everyone: An In-Depth Tutorial on How GraphQL Works and Why It's Special.
To get Postman to accept a GQL Query, you select the GraphQL option as shown below in Figure 2, callout (1). Then, enter the query into the QUERY pane as shown at callout (2). Finally, click the Send button to execute the query as shown at callout (3).
Figure 2: Postman allows developers to declare GraphQL queries directly in GraphQL Query Language. Viewing Query Results
After you execute a GraphQL query as shown in Figure 3 callout (1) below, the results will appear under the Body tab of response pane at the bottom of the Postman GUI, as shown at callout (2).
Figure 3: The results of a GraphQL Query
Working with GraphQL Query Variables in Postman
GraphQL supports the concept of query variables. Using query variables allows you to define a set of variables that can be used repeatedly over a variety of queries.