skip to content

In a Postman collection url object, what does a colon-prefixed path segment mean, and how is it resolved?

level: middleimportance: should knowfreq 45%

answer

  1. A leading colon marks a hole
  2. The value lives beside the path
  3. Named in path, valued in variable
  4. getPath puts the two together
  5. Shape stored, value substituted on render

basics

~20 s

A segment written with a leading colon, such as :orderId, is a path variable rather than a literal. Its value lives in the same url object's variable list, and the SDK's getPath reads those segments when rendering the path.

solid answer

~40 s

Inside a structured `url`, `path` is a list of segments, and a segment written with a leading colon — `:orderId` — is a **path variable**, not a literal segment. Its value lives in the same url object's `variable` list, as an entry whose `key` matches the name after the colon. The SDK's `getPath` reads those colon-prefixed segments when it renders the path, so the outgoing address carries the value while the stored document keeps the shape. That is the point: the saved request shows *which segment varies* rather than freezing one caller's identifier into the address, and anyone reading the file sees the structure of the endpoint at a glance. Note the `variable` list here belongs to the url object itself; it is not the same thing as a collection-wide or environment store.

code

json · 11 lines
json
{
  "url": {
    "raw": "https://api.example.com/orders/:orderId",
    "protocol": "https",
    "host": "api.example.com",
    "path": ["orders", ":orderId"],
    "variable": [
      { "key": "orderId", "value": "ord-alpha" }
    ]
  }
}

go deeper

for a junior

Recall that a path segment starting with a colon is a placeholder, not literal text, and that its value is stored elsewhere in the same url object.

for a middle

Explain the mechanics: the placeholder name lives in the path segments, the value in the url object's variable list, and getPath reads those segments when rendering the path.

for a senior

Show the document-level payoff — saved requests describe an endpoint rather than one sample id, stay comparable in review, and retarget by editing a value instead of an address.

for a principal

Own the convention across a shared collection: which segments must be placeholders, how imported or generated requests are normalised, and how tooling avoids baking sample identifiers into stored paths.

## A segment that is a placeholder In a structured `url` inside a **Postman collection**, the `path` member is the address's path expressed as segments. Most segments are literal text. A segment written with a **leading colon** — `:orderId`, `:userId` — is different: it is a **path variable**, a named hole in the address rather than a piece of the address itself. The value that fills the hole is not stored inside the segment. It lives in the same url object's `variable` member, a list of entries whose `key` matches the name after the colon. So the shape of the address and the value currently standing in it are recorded in two different places, deliberately. ## How it is read The format records the segments and the list; the **SDK** is what turns them back into a path. Its `getPath` reads the colon-prefixed segments as it walks the path, so the rendered path carries the value while the stored document keeps the placeholder. That produces a clean division: | | stored in the document | seen in the rendered path | |---|---|---| | literal segment | the text itself | the same text | | colon-prefixed segment | the placeholder name | the value from `variable` | | the value | an entry in `variable` | substituted into position | ## Why store an id this way at all Writing the id straight into the path works — the request will send — so the reasons for the placeholder are all about the document, not the call: - **The saved request shows the endpoint, not one caller's example.** `orders/:orderId` describes a shape; `orders/ord-alpha` describes one row somebody happened to look at. - **The varying part is named.** A reader can tell at a glance which segment is meant to change, without guessing whether a segment that looks like an identifier is one. - **The value is editable in one place.** Changing the entry in `variable` changes what the request calls without touching the path at all. - **Requests stay comparable.** Several saved requests against the same endpoint keep the same path, so a diff or a review shows real differences rather than differing sample ids. ## Reading such a url correctly A few practical rules for anyone writing tooling over collections: 1. **Do not treat a colon-prefixed segment as text.** A script that string-matches paths will otherwise see `:orderId` as part of the endpoint and fail to group requests that share it. 2. **Look for the matching `variable` entry.** The name after the colon is the `key` to find. An absent entry means the placeholder has no value stored with the request. 3. **Remember `raw` is a summary.** The url object still carries the whole address as `raw`; do not reconstruct the path from `raw` when the segments and the `variable` list are right there. 4. **Keep the placeholder when rewriting.** Tooling that normalises addresses should preserve the colon segment rather than baking the current value into the path. ## What this is not Two neighbouring ideas are commonly muddled with this one, and an interview answer is stronger for separating them. The first is scope. The `variable` list discussed here belongs to **this url object**: it holds the values for this request's own path placeholders. Collection-wide sets, environment sets and the order in which layered stores are consulted are separate subjects with their own mechanics; do not describe the url's list as if it were one of them. The second is the brace-token syntax used elsewhere in collections for substitution. Colon-prefixed path variables are a **path** construct, recorded segment-by-segment and read by `getPath`; brace expansion is a different mechanism with its own resolution rules. Answering "it is just another variable" flattens two things that live in different places in the file and are resolved by different code. Finally, none of this is about how a URI *should* be designed — whether an identifier belongs in the path at all, how to keep an address stable, or what a good path grammar looks like. Those are API-design questions. Here the subject is narrower and entirely mechanical: a saved address records the varying segment by name, stores its value beside it, and the SDK puts the two together when it renders the path.

  • What is lost if the identifier is written straight into the path instead of as a colon-prefixed segment?
    The document stops describing the endpoint and starts describing one example call. Nothing marks which segment varies, saved requests against the same endpoint no longer share a path, and changing the target means editing the address rather than one entry in the url object's `variable` list.
  • Is the url object's variable list the same as a collection-wide variable set?
    No. The list inside the url object holds values for that request's own colon-prefixed path segments. Collection-wide and environment sets are separate stores with their own mechanics and their own resolution rules; conflating them misplaces where the value is actually recorded.

saying these in an interview costs you the question

  • Treats a colon-prefixed segment as literal path text
  • Thinks the value is stored inside the segment itself
  • Calls the url's variable list a collection-wide store
  • Confuses colon path variables with brace-token substitution
  • Rebuilds the path from raw and ignores the segments