From 13d38daf3ceca72f0dc9fa79c50f1eb5dab16b14 Mon Sep 17 00:00:00 2001 From: Roberto Tyley Date: Wed, 16 Sep 2026 16:19:24 +0100 Subject: [PATCH 1/2] Update docs on `Content.id` (CAPI id) to reflect Evolving URLs 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 https://github.com/guardian/ophan/pull/4075 --- models/src/main/thrift/content/v1.thrift | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/models/src/main/thrift/content/v1.thrift b/models/src/main/thrift/content/v1.thrift index 99eefd3..3c61700 100644 --- a/models/src/main/thrift/content/v1.thrift +++ b/models/src/main/thrift/content/v1.thrift @@ -1980,7 +1980,17 @@ 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. + * + * 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*. + * + * Note that in our internal Preview CAPI service, the CAPI id is *not* fixed until the content is launched. */ 1: required string id From 029b091248fad306b917b06964408df2179ab82f Mon Sep 17 00:00:00 2001 From: Roberto Tyley Date: Thu, 17 Sep 2026 11:55:14 +0100 Subject: [PATCH 2/2] Add additional notes to cover the possibility of a CAPI id changing if content is taken down and republished Updated in response to: * https://github.com/guardian/content-api-models/pull/335#pullrequestreview-5225418187 --- models/src/main/thrift/content/v1.thrift | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/models/src/main/thrift/content/v1.thrift b/models/src/main/thrift/content/v1.thrift index 3c61700..7f8c32d 100644 --- a/models/src/main/thrift/content/v1.thrift +++ b/models/src/main/thrift/content/v1.thrift @@ -1981,7 +1981,7 @@ struct Content { /* * 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. + * 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 @@ -1990,7 +1990,13 @@ struct Content { * 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. + * 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