Introducing GraphMan: instantly scaffold a Postman collection for your GraphQL API

Graphman presentation image

While querying, developing, and testing your GraphQL APIs with postman is easy and convenient, it has a big caveat: if you want to cover an endpoint with all its queries and mutations entirely, it will take you hours and repetitive steps to create every request, and you'll almost surely miss queries, arguments or fields.

However, GraphQL APIs can provide their schema, which describes the complete endpoint exhaustively, and this can be exploited for many things: autocompletion, type-safety, etc. Why not use it to create postman collections automatically?

Here comes GraphMan: a simple CLI tool that allows you to create a complete collection of requests from a GraphQL endpoint URL that covers your whole API in a matter of seconds.

🚀 Generate a postman collection with GraphMan

I'll give you a quick step-by-step guide of GraphMan to generate a collection for the public Rick and Morty API.

Graphman is written in Typescript and uses the Deno runtime; there is no need to download or install it. You can run it directly from the source URL:

You will obtain the collection as a .json in your current working directory, import it in postman with the "import" button, and you'll obtain the following collection:

The created collection features one request per query and mutation, covering the whole API.

The queries (resp. mutations) are pre-filled with every available field, but object fields are commented (see origin, location, and episode fields here) to prevent infinite nested trees, making the requests impossible to read for any healthy human being. You can get those fields by uncommenting them and writing the desired subfields using postman autocompletion. Every argument is also defined and tied to a variable, whose value will default to null if nullable else it will have a default value based on its type.

You can see that it's very straightforward to use and provides a complete and easy-to-read collection of queries!

Here are some cool use-cases:

  • You want to discover an already existing GraphQL API, whether you're a backend, frontend developer, or you want to play with GraphQL. 👀
  • You want to document and test your whole API for your team without forgetting anything. 📚
  • You want to keep your postman collection up to date with your schema. ♻️

The GitHub repository of GraphMan is here: https://github.com/Escape-Technologies/graphman; feel free to open issues for bugs or suggestions and collaborate!

🎉 Conclusion

If you want to learn more about GraphQL, take a look at their documentation: https://graphql.org/ and read our other articles: https://blog.escape.tech/ 🤓

Finally, now that you know how to test and document your GraphQL API with Postman and GrapmMan, you surely want and absolutely need to secure it! To do so, head to https://escape.tech/ to discover Escape, our all-in-one GraphQL security tool. Claim your free trial now to start thousands of tests on your API at the push of a button! 🚀