Your team commits a Postman collection to version control — what should a reviewer check in each request's url?

## Why the url needs a reviewer at all Once a **Postman collection** is committed, it stops being a scratchpad and becomes a shared artefact: it is read, diffed, merged and re-imported by people who did not type it. The `url` of each stored request is the part of that artefact most likely to carry both noise and something you would rather not commit, because it is the field people edit most often and inspect least carefully. A reviewer is not checking whether the address is *correct* — the request either works or it does not. The review question is different: **is this address stored in a form the team can keep maintaining, and does it carry anything it should not?** ## The three checks that matter 1. **Is `url` a flat string or an object?** Both are legal in the format. The flat string form puts the entire address in one value, which means every conceivable edit — a host swap, one parameter, a path segment — appears as a single changed line, and a reviewer must diff it by eye. The object form breaks the address into `raw`, `protocol`, `host`, `path`, `port`, `query`, `hash` and `variable`, so a change to one parameter moves one line and reads as itself. 2. **Does any `query` entry carry `disabled` with a live value?** The flag suppresses sending, not storing. The entry keeps its `key` and `value` in the file, and the SDK's `QueryParam.unparse` simply leaves it out when building the query string. A parameter someone unticked before committing is still in the repository, and it is one tick away from being sent again. 3. **Are varying identifiers placeholders or literals?** A path segment written with a leading colon is a path variable whose value sits in the url object's `variable` list, and the SDK's `getPath` reads those segments when rendering the path. A literal id baked into `path` turns a request that documents an endpoint into a request that documents one example call. ## What each finding actually means | what you see | what it tells you | what to ask for | |---|---|---| | `url` as a flat string | future edits will be unreviewable one-liners | store the structured object form | | an entry with `"disabled": true` | a value is stored that the wire never carries | delete the entry if the value should not be committed | | a literal identifier in `path` | the request records an example, not an endpoint | a colon-prefixed segment plus a `variable` entry | | `raw` disagreeing with the parts | somebody edited one view and not the other | reconcile, and prefer the named parts | | a huge, opaque address | the parts were never broken out | break them out before merging | ## Reviewing the diff, not just the file A collection diff is dominated by mechanical churn: exports reorder and re-emit far more than was actually changed. That makes the review discipline different from ordinary code review. - **Read added lines for values, not just for keys.** A new `query` entry is a new stored value regardless of the flag on it. - **Do not trust a run as evidence.** Watching traffic from a collection run tells you what was sent. It cannot tell you what is parked in the document, because disabled entries never appear on the wire. - **Treat shape changes as substantive.** A request quietly converted from the object form to a flat string has lost reviewability for everyone downstream, even though the address is identical. - **Check that placeholders survived tooling.** Generators and rewrites sometimes bake the current value into the path; the colon segment should still be there afterwards. ## Setting the standard rather than catching each case At team scale, per-review vigilance is the weakest control. The stronger move is to make the desired form the default and check it mechanically: a script that walks every request in the file, reports any `url` stored as a string, lists every `query` entry carrying `disabled`, and flags path segments that look like identifiers without a colon. All three are trivially checkable, because they are plain members of the document — which is precisely the argument for keeping addresses in the structured form in the first place. One boundary is worth stating out loud in the review itself. Whether an identifier belongs in a path at all, how the query grammar should look, and how the API's addresses ought to be designed are **API-design** questions and belong to whoever owns the interface. The reviewer's remit here stops at the stored document: its shape, what it carries, and whether the next person can change it safely.