When would an API return a parameterised link such as /orders{?status,page} marked templated instead of a fully resolved URL, and what does RFC 6570 expansion require the client to do with it?

## Resolved link versus template A hypermedia response mostly carries links the server has already computed - self, next, the URL of a related resource. Those are ready to use. But some affordances are not a single URL: a search endpoint, a filterable collection, or a lookup by an identifier the client holds. Enumerating every combination is impossible, so the server publishes a URI Template (RFC 6570) and lets the client fill it in. Because the two look alike in JSON, formats mark templates explicitly - typically a templated: true flag next to the href. A client that ignores the flag and requests the raw string will send braces on the wire and get a 404 or a rejected request. ## The syntax, briefly A template is a string with expressions in braces. The first character of an expression may be an operator: - **{var}** simple expansion - substitutes a percent-encoded value. - **{+var}** reserved expansion - permits reserved characters like / and ? through unencoded, used when the variable holds a path fragment. - **{#var}** fragment expansion. - **{/var}** path-segment expansion - prefixes a slash. - **{?a,b}** form-style query - emits ?a=1&b=2, and emits nothing at all if no variable is defined. - **{&a}** continuation - appends &a=1 to a URL that already has a query. - **{var*}** explode modifier - expands a list or map into repeated or paired parameters. - **{var:3}** prefix modifier - truncates to the first 3 characters. RFC 6570 organises these into levels 1 to 4, level 1 being plain {var} substitution and level 4 adding modifiers. Many client libraries implement level 4 fully. ## What the client must do Use a library, not string replace. Correct expansion involves per-operator encoding rules, the difference between reserved and unreserved character sets, list and map handling, and the rule that undefined variables simply disappear - which is what makes {?status,page} degrade cleanly to a bare collection URL when the caller supplies nothing. Hand-rolled substitution gets encoding wrong the first time a value contains a space, an ampersand or a non-ASCII character. ## The coupling trade-off This is the part worth saying out loud. The promise of hypermedia is that the client depends on relation names, not on URL structure. A template partially retracts that: the client must now know that the variable is called status and that its legal values are PENDING or SHIPPED. The URL shape is still the server's business, but the parameter vocabulary becomes a shared contract that has to be documented and versioned like any other. Adding a new optional variable is safe; renaming or removing one breaks callers. That is why the usual guidance is: prefer resolved links wherever the server knows the target, and reserve templates for genuinely caller-parameterised access - search, filtering, sorting, direct lookup by an identifier the client already possesses. Pagination is the classic case for resolved links precisely because the server knows what the next page is and can hide cursors, offsets and sort state inside an opaque href. ## Practical notes - Give the template a relation name like any other link, and document the variables alongside that relation. - Do not put secrets or signed values into templates the client fills in; the server cannot sign what it did not build. - Templates and content negotiation are independent - a template describes a URL, not a representation. - Server-side helpers can build templates from route definitions, which keeps them from drifting away from the actual routing table.