Postman Collections

pidl generate -f postman turns a PIDL file into a Postman collection you can run: a folder for each scenario, a request for each step the client role sends, values passed from each response to the next request, and checks on every response. The collection is generated from the same examples the walkthrough viewer shows, so the two agree step for step.

# Signed requests sent through a signing proxy
pidl generate -f postman --signer proxy -o api.postman_collection.json oauth2_api_access

# Requests sent directly, with saved example responses for a Postman mock server
pidl generate -f postman --mock -o api-mock.postman_collection.json oauth2_api_access

What Is Generated

Part	From
Folders	Groups, then scenarios, in output order; fragments expanded in place
Requests	Steps whose sender is the client role (--client, default: the first agent or client entity) and that have an example request
URLs	Each role's base URL becomes a variable such as {{ps_url}}
Chained values	A value an earlier response delivers (a body member, a Location or another header, or a string parameter of a header, such as the scope of a WWW-Authenticate challenge or a parameter of a structured field) and a later request reuses is saved to a collection variable and referenced as {{name}}
Checks	Status code; headers named in the example; body members; and the claim names of tokens the body carries
Deferred responses	A request answered 202 with Location accepts either the 202 (then the next request polls {{location}} until it completes) or the final response (then the poll is skipped)
Folder notes	The scenario's description and narration, and the steps between other roles that the collection does not send

Signing Proxies

Postman cannot create HTTP message signatures (RFC 9421). With --signer proxy, each request whose example is signed goes to {{signer_url}}/<target URL>, and a signing proxy signs it and forwards it. Requests without signatures are sent directly.

Header	Sent to the proxy
Signature, Signature-Input, Content-Digest	Left out; the proxy creates them
Signature-Key	How to sign: the example's label and scheme, such as sig=hwk. For the jwt scheme it also carries the token to present when an earlier response delivered it, sig=jwt;jwt="{{user_token}}"; without one, the proxy presents its own
Everything else	As in the example, with chained values

The proxy decides what each token means for its protocol. An implementation of a signed protocol can provide one for testing: the AAuth sandbox in aauth-go is a signing proxy for AAuth.

Environments

An environment says where a target's roles run. Write targets in a JSON file:

{
  "local": {
    "signer": "http://127.0.0.1:8099",
    "roles": {
      "as": "https://as.local.test",
      "api": "https://api.local.test"
    },
    "scenarios": {
      "async-export": {"api": "https://exports.local.test"}
    }
  },
  "mock": {
    "roles": {"as": "{{mock_url}}", "api": "{{mock_url}}"},
    "variables": {"mock_url": "https://<your-mock-id>.mock.pstmn.io"}
  }
}

pidl generate -f postman-environment --targets targets.json --target local -o local.postman_environment.json oauth2_api_access

scenarios points a role at another server for one scenario's folder only: here, the asynchronous export goes to a separate export service. Without --targets, the environment uses the base URLs of the examples.

Running

Import the collection and an environment into Postman and run a folder, or use Newman:

npx newman run api.postman_collection.json -e local.postman_environment.json --folder "Asynchronous export"

Collections are generated output: edit the PIDL file and regenerate rather than editing the collection.