How does WunderGraph work with Postman Collections

Postman is a popular tool to try out APIs.

Aside from testing APIs and playing with them, Postman has another powerful feature, Postman Collections.

Postman Collections#

Postman Collections are very similar to Swagger or OpenAPI Specifications. They make it very easy to try out and share a predefined set of functionalities of an API. This way, you don't have to build all the URLs, Query Parameters, Headers, etc. by hand.

Postman and WunderGraph#

As you might have already learned, WunderGraph uses GraphQL as the API orchestration layer and only exposes a JSON API. This JSON API has unique URLs for each operation as well as a JSON Schema for the inputs as well as the response objects.

One of the features of WunderGraph is that we're automatically generating a Postman Collection for all your operations. You're able to import this collection, a JSON description, into your Postman application to try out your configured API immediately.

As an additional benefit, you can share the generated Postman collection with your team or a partner you're working with.

Use cases#

If you're working with a diverse set of partners, you can build a specific API for each of them just by writing a few GraphQL Operations against your virtual GraphQL.

Not everybody has the capability or bandwidth to learn GraphQL. If you wrap it with a JSON API and create a Postman Collection, you allow partners to use your API without having them to learn GraphQL.

WunderGraph allows you to add DataSources like GraphQL, REST (OpenAPI Specification), PostgreSQL and MySQL to a virtual Graph. This Graph can be exposed as a secure JSON API with features like Authentication, Authorization and Caching with very little configuration. You can leverage this by turning any of these DataSources into carefully locked down micro APIs for specific use cases or users. Add a DataSource, write one or more Operations, configure Security and Authentication, done. Share the generated Postman Collection and move forward. The virutal Graph as a business enabler.

Example#

Let's assume we're building a Realtime Chat where users can add messages. The Mutation to create a message might look like this:

mutation (
    $name: String! @fromClaim(name: NAME)
    $email: String! @fromClaim(name: EMAIL)
    $message: String! @jsonSchema(
        pattern: "^[a-zA-Z 0-9]+$"
    )
){
    createOnepost(data: {message: $message user: {connectOrCreate: {where: {email: $email} create: {email: $email name: $name}}}}){
        id
        message
        user {
            id
            name
            email
        }
    }
}

Now let's have a look at the equivalent generated Postman Collection, .wundergraph/wundergraph.postman.json from your Project root:

{
  "item": [
    {
      "_": {
        "postman_id": "XXX_redacted"
      },
      "id": "XXX_redacted",
      "name": "Mutations",
      "description": {
        "content": "All your mutation operations",
        "type": "text/plain"
      },
      "item": [
        {
          "id": "XXX_redacted",
          "name": "CreatePost",
          "request": {
            "url": {
              "path": [
                "api",
                "main",
                "operations",
                "CreatePost"
              ],
              "host": [
                "{{apiBaseUrl}}"
              ],
              "query": [],
              "variable": []
            },
            "method": "POST",
            "body": {
              "mode": "urlencoded",
              "urlencoded": [
                {
                  "disabled": true,
                  "description": {
                    "content": "Type string",
                    "type": "text/plain"
                  },
                  "key": "message",
                  "value": ""
                }
              ]
            }
          },
          "response": [],
          "event": []
        }
      ],
      "event": []
    }
  ],
  "event": [],
  "variable": [
    {
      "type": "string",
      "value": "http://localhost:9991",
      "key": "apiBaseUrl"
    }
  ],
  "info": {
    "_postman_id": "XXX_redacted",
    "name": "Wundergraph",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "description": {
      "content": "Your Wundergraph collection",
      "type": "text/plain"
    }
  }
}

If you deploy this API using WunderGraph, the equivalent Endpoint will look like this:

http://localhost:9991/api/main/operations/CreatePost?message=hello

Building this URL could be a bit complicated. Additionally, the Query Parameter message is already defined and has a description and encoding is set to x-www-form-url-encoded. Just hit the checkbox, add a message, and click "Send".