Convert a GraphQL schema into a Postman Collection with GraphMan

This is a guest post written by Nohé Hinniger-Foray, R&D engineer at Escape Technologies.

GraphQL is one of the most popular query languages for building APIs. It employs a schema-focused approach, describes the structure of the data being returned, and allows the API consumer to query the exact data they need.

Postman’s built-in support for GraphQL allows you to import a GraphQL schema and convert it into a Postman Collection with the Postman API Builder, which uses the graphql-to-postman module. There may be times, however, when you need to programmatically convert your GraphQL schema into a collection from within your code, via the command line, or with other tooling in separate workflows.

GraphMan, which was developed by Escape Technologies, is an open source command-line tool that allows you to easily convert your GraphQL schema into a Postman Collection. It is similar to Postman’s graphql-to-postman module, but it lets you do this conversion on the command line. It introspects your GraphQL endpoint and generates one request per mutation or query, enabling you to quickly create a collection and start taking advantage of Postman’s full feature suite.

Installation and usage

GraphMan is completely written in TypeScript and runs on the Deno runtime, so you can directly run the CLI from a remote source. To do so, simply install Deno and run deno run https://deno.land/x/graphman@v1.2.0/src/cli.ts <graphql endpoint url>. You’ll get a  .postman-collection.json file that you can directly import into Postman to start querying your API.

GraphMan use cases

Converting a GraphQL schema into a Postman Collection opens up a wide range of use cases that aren’t supported by other GraphQL clients. For instance, you can:

• Monitor your GraphQL API’s uptime, execute tests at predefined intervals, and evaluate performance across different environments with Postman Monitors.
• Create example responses for different mutations and queries, which can help consumers get up to speed quickly.
• Collaborate with other developers on your GraphQL APIs with Postman’s built-in commenting and version control features.
• Test and run your GraphQL APIs on the command line or in your CI/CD workflows with the Postman CLI.
• Easily document your GraphQL APIs, and enhance your documentation with tables, images, and environment variables.
• Expose your GraphQL APIs and collections to a community of over 20 million developers in Postman’s Public API Network.

What’s next for GraphMan

While GraphMan currently allows developers to convert a GraphQL schema to a collection, it will ultimately enable them to convert a Postman Collection into a GraphQL schema, as well. Users can also expect better default typing in GraphMan’s codebase, as well as the ability to export GraphMan as an npm package for full compatibility with Node.js.

To learn more about GraphMan, visit its official repository. You can contribute to the project by resolving issues (check out issues with the “good first issue” tag), reporting bugs, submitting feature requests, and inviting others. Escape’s GraphQL security platform also integrates nicely with Postman, so you can automatically discover vulnerabilities within your GraphQL API.