Update docs on Content.id (CAPI id) to reflect Evolving URLs - #335
Conversation
See also: * https://docs.google.com/document/d/1s6xsGHcQOgdPBTbGYwqTXuCz90e3lHKOnkBFW6yCvqY/edit * https://github.com/guardian/flexible-content/issues?q=state%3Aclosed%20label%3A%22Evolving%20URLs%22%20sort%3Acreated-asc * https://github.com/guardian/ophan/issues?q=label%3A%22Evolving%20Urls%22%20sort%3Acreated-asc , especially guardian/ophan#4075
rtyley
added
the
maintenance
There was a problem hiding this comment.
🟢 Approval recommended
The documentation-only change is clear, internally consistent, and matches the stated purpose.
Pull request overview
Updates Content.id documentation to reflect immutable CAPI IDs and evolving content URLs.
Changes:
- Clarifies that live CAPI IDs are immutable and should be treated as opaque.
- Documents URL changes and Preview CAPI behavior.
File summaries
| File | Description |
|---|---|
models/src/main/thrift/content/v1.thrift |
Corrects and expands Content.id documentation. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| * changed by Editorial Staff. In this case, in the Content API, the content's webUrl will change, but the CAPI id | ||
| * will *not*. | ||
| * | ||
| * Note that in our internal Preview CAPI service, the CAPI id is *not* fixed until the content is launched. |
There was a problem hiding this comment.
All true, might be worth noting that regardless of changes to the actual path via the evolve url process, the content's id will always lead to the correct document, and the id remains fixed unless it is taken down and launched with a new one.
There was a problem hiding this comment.
Ah thanks, I hadn't realised that a CAPI id can change if an item of content is taken-down, has its path altered, and is then republished - I did that just now to an article in CODE to see it happen:
- https://preview.code.dev-gutools.co.uk/technology/2026/sep/17/this-piece-of-content-has-a-new-path-but-will-it-get-a-new-capi-id
- https://composer.code.dev-gutools.co.uk/content/6aabafea8f08b025a0223b34
- https://content.code.dev-guardianapis.com/technology/2026/sep/17/can-a-piece-of-content-change-its-capi-id-if-it-is-taken-down?format=json&show-fields=all&show-alias-paths=true&api-key=[API_KEY]
I can see why that might be necessary, for instance if the URL path itself contains a libel!
I've added a note regarding that aspect in 029b091
JustinPinner
left a comment
JustinPinner
left a comment
There was a problem hiding this comment.
👍 (my comment is non-blocking)
…f content is taken down and republished Updated in response to: * #335 (review)
The Evolving URLs work took place in 2020-2021, this means that the
Content.id(CAPI id) is no longer guaranteed to be the URL path of the content!In our current AB-testing work, this has led to some confusion, and I've seen LLMs saying incorrect things, due to them taking this line of documentation as gospel:
content-api-models/models/src/main/thrift/content/v1.thrift
Line 1983 in a78b7d5
See also historical PRs on Evolving URLs: