PostmanDiscovery6 min readTurning a private request into team knowledge
A saved request is documentation that can be run.
- The surface
- Sending a first request, saving it into a collection, adding environment variables, and sharing the collection with a team.
- What the user wants
- I want to understand what this API actually returns, and I want the next person not to have to work it out again.
Send before you configure
A new tab accepts a method and a URL and sends immediately, with authentication, headers and body available and not required.
Shortest path to a first result
The user's real question is what does this endpoint do, and every required field before the send button delays the answer. Letting an unauthenticated request fail informatively is faster than a setup form. The error itself teaches what configuration is needed.
The response pane
The response shows the body with syntax highlighting alongside status code, time and size, plus headers and cookies in their own tabs.
Show the whole answer, not the part you expected
Debugging an integration usually turns on something outside the body, such as a content type or a cache header. Presenting status, timing and headers with equal prominence means the clue is already on screen. The user does not have to know what to look for before they can see it.
Saving into a collection
A request can be saved with a name and description into a folder structure, so a collection becomes an ordered set of real, runnable calls.
Capture the work as the artifact
The expensive part of learning an API is the trial and error, and normally all of it is thrown away. Saving converts exploration into a reusable asset at almost no marginal effort. The team's knowledge accumulates as a side effect of one person doing their job.
Environments and variables
Values like the base URL and tokens are stored in a named environment and referenced in requests by variable, so the same collection runs against staging or production by switching a dropdown.
Parameterise the thing that changes
Without this, teams keep duplicate collections per environment and they drift within days. One collection and several environments keeps a single source of truth. The dropdown also makes it visible which environment you are about to hit, which prevents an entire category of accident.
Tests attached to requests
A request can carry assertions that run against its response, and a collection can be executed as a sequence with a pass and fail summary.
Let the exploration harden into a check
The line between exploring an API and monitoring it is thinner than most tools acknowledge. Attaching assertions to an existing request means the step from I checked this to this is checked automatically is small. Work that would otherwise need a rewrite in a test framework is promoted in place.
Sharing the collection
Collections live in a workspace others can join, and documentation views are generated from the saved requests and their descriptions.
Documentation derived from the working artifact
Hand-written API docs drift because they are maintained separately from the thing they describe. Generating from requests people actually run keeps the docs closer to reality. The weakness is that quality depends on descriptions nobody is forced to write.
Turning a throwaway request into the team's notes
What not to copy
- The product has grown from a request client into a platform, and the interface carries that history. A first-time user looking for a send button now navigates workspaces, collections and account state first.
- Shared workspaces and stored environments are a credential leak waiting to happen. Tokens saved for convenience sync to places their owner did not picture.
- Cloud sync as the default path unsettles teams who considered this a local tool. The choice to keep work off a vendor's servers is available and is not the easy one.
- Generated documentation is only as honest as the descriptions people bothered to write, and a collection of forty unnamed requests published as docs is worse than no docs, because it looks official.
The takeaway
Look for the throwaway work in your product's flow and make saving it the default.
Finished the teardown? Bank it and the day counts toward your run.
Where the principles come from
- The Design of Everyday Things (feedback and visibility), Don Norman
- Don't Make Me Think, Steve Krug
- Visibility of System Status (heuristic 1), NN/g
Written from public behaviour of the product, not from inside it. Interfaces change often, so treat the flow described here as of the time of writing and check the live product before quoting it.