Friendly URLs

How Friendly URLs Work

A friendly URL turns an address full of parameters into one a person can read and share.

Where to find it

Architect Panel → Configuration:

• Friendly URLs — the rules that generate readable addresses

Architect Panel → Data:

• Datastores — the records a rule generates paths for

A rule belongs to a datastore

Each rule names a root path and a configuration: which datastore, which field supplies the text, what prefix the real destination uses, what replaces spaces, and — where records nest — which field points at the parent.

So one rule covers an entire datastore rather than being written per record.

Paths are generated as records change

Creating, updating, restoring or rolling back a record runs the rule for its datastore. So the addresses stay in step with the data without anybody maintaining them.

Uniqueness is handled

If a generated path is already taken, a number is appended until it is not. Two products called "Blue Widget" get distinct addresses rather than one overwriting the other.

Which is convenient and worth knowing: an address ending in a 2 usually means a duplicate name rather than a mistake.

The cache is the routing table

Generated paths are held in a cache mapping each path to its real destination, along with the rule and the record it came from. That is what the site actually consults when a request arrives.

So if an address is not resolving, the question is whether it is in the cache — not whether the rule looks right.

Nested records produce nested paths

Where a rule names a parent field, the path reflects the hierarchy. A category three levels deep produces an address showing all three, which is both readable and good for search engines.

Choose the source field carefully

It should be something meaningful, stable and unlikely to be edited casually. A name is usually right; a description is too long, and a status is not unique.

Friendly URLs are a security-sensitive area

The routing tables are on the platform’s protected list, because anybody able to write to them could redirect your addresses somewhere else. They are not editable through the API for that reason.

Set them up before launch

Addresses that change after publication break bookmarks, links and search rankings. Getting the path structure right first is much cheaper than redirecting later.

Worked example

A site generates product addresses from the product name under a products root, with categories nested by their parent field. Two identically named products produced distinct addresses automatically. When a page stopped resolving, the cache showed the record had been renamed and the old path was simply gone.

Recommendations

• Generate from a stable, meaningful field.
• Check the cache when an address does not resolve.
• Settle the path structure before launch.
• Treat the routing tables as sensitive.

Setting Up a Rule

A rule is one row and a handful of decisions that are awkward to revisit.

Where to find it

Architect Panel → Configuration:

• Friendly URLs — the rules that generate readable addresses

The root path

The segment every generated address sits under. Short, lower case, plural, and describing the thing — products, articles, jobs.

Avoid anything that looks like a file or a system path, and avoid words you might want for a real page later.

The source field

The field the readable part comes from. Choose one that is:

• Meaningful — a person should recognise what the page is from the address.
• Stable — renaming a record changes its address.
• Reasonably short — a long address is truncated everywhere it is displayed.

The space replacer

A hyphen conventionally. Underscores work but read less well and are treated differently by some search engines. Whatever you choose, be consistent across every rule on the site.

The destination prefix

Where the friendly address actually points — the real page with its parameter. Get this right first, because every generated path uses it, and a wrong prefix means every address in that rule resolves to the wrong place.

Nesting

Where the datastore has a parent field, naming it produces hierarchical addresses. Worth doing where the hierarchy is meaningful to a reader and worth skipping where it is only meaningful internally.

Test with awkward records

Not with a tidy example. Try a record whose name has an apostrophe, an ampersand, an accent, a very long name, and one that duplicates another. Those four cover nearly every generation problem.

Check what an existing record generates

Rules apply as records change, so an existing record does not necessarily have a path until it is next saved. Confirm what your existing data produces rather than assuming the rule applies retrospectively.

Renaming breaks links

The consequence people forget. A record renamed gets a new address, and the old one stops working — for bookmarks, for e-mails sent last month, and for search results.

Where addresses matter commercially, treat renaming as a decision rather than an edit.

Worked example

A site created a products rule under a short root with hyphens and the product name as the source, tested with a name containing an ampersand and a duplicate, and confirmed the destination prefix before enabling it. Product renaming was made a two-person decision because of the link breakage.

Recommendations

• Short, plural root paths that will not clash with real pages.
• Hyphens, consistently, across every rule.
• Test with awkward names, not tidy ones.
• Treat renaming as breaking a link, because it is.