Skip to content

Update docs on Content.id (CAPI id) to reflect Evolving URLs #335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rtyley merged 2 commits into from
Sep 17, 2026
Merged

Update docs on Content.id (CAPI id) to reflect Evolving URLs #335

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
13d38da
Update docs on `Content.id` (CAPI id) to reflect Evolving URLs
rtyley Sep 16, 2026
029b091
Add additional notes to cover the possibility of a CAPI id changing i…
rtyley Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion models/src/main/thrift/content/v1.thrift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1980,7 +1980,23 @@ struct ContentChannel {
struct Content {

/*
* The id of this item of content: this should always be the path to the item on www.theguardian.com
* The CAPI id of this item of content: once the content is launched, this value will not change, so for
* all content in our Live CAPI system, this value is immutable while the content is live.
*
* Although it's probably best to think of the CAPI id as an opaque value (we shouldn't derive any meaning from it,
* let alone rely on it being a 'path' value), it _does_ take the value of the *initial* path of the URL of the
* item when published to www.theguardian.com. It's worth noting that with the introduction of 'Evolving URLs'
* functionality to the Guardian CMS in 2020, the URL path of a live published piece of Guardian content *can* be
* changed by Editorial Staff. In this case, in the Content API, the content's webUrl will change, but the CAPI id
* will *not*.
*
* Additional points:
*
* - In our internal Preview CAPI service, the CAPI id is *not* fixed until the content is launched.
* - The CAPI id for a live piece of content _can_ change in the rare case that it is taken-down after
* launch, has its path altered (perhaps for legal reasons) and is then republished. Note that this maintains
* the rule that the CAPI id is immutable while content is live, the content has to undergo two state
* transitions (live to draft, to live again) in order for the CAPI id to change.
*/
1: required string id

Expand Down
Loading