Discussion: Moving away from Prismic IDs

[rcantin-w]

While writing an RFC for the Events endpoints, we also started questioning our use of the Prismic IDs across the API. We posted about it on Slack and Robert replied with a suggestion that deserves its own ticket/discussion, so we're creating this to unblock the original RFC.

Challenge

We currently mostly work with Prismic IDs (e.g. format=WcKmiysAACx_A8NR), the exceptions being boolean filters and strings (enums). It makes URLs hard to read, plus, since the content-api’s raison d’être is, at least partly, about decoupling our content from Prismic, it’s something we’d like to address. But how? Our only other option is using the labels.

Pros:

• It allows us to use human-readable values in the url, eg. "workshop" instead of "WcKmiysAACx_A8NR"
• weco.org doesn’t need to know about Prismic IDs
• It’s more in line with the Catalogue API filters

Cons:

• Many of these values have spaces in them, eg. "Thomas S G Farnetti", which will have to be encoded in the url, reducing the “human-readability”
• Labels may be less stable than ids, as the editorial team can change the label text at any time, which would cause extra work on the FE to align the filters in the request to the new values.
• All filters will have to be sent as <filterName>.label since we will be filtering on an attribute other than the identifier

Suggested solution

• The content-pipeline generates "slugs" from labels which it stores as stable (though manually editable if necessary) ids for content and we keep track of the prismic-id / content-api slug-id in a service in the content pipeline (an id-minter-ish thing). Changing the label after initial creation would not cause the mapping to update.
• When you request content from the content-api with the slug-id a new id lookup service looks up the mapping to Prismic ID and requests the right stuff from Prismic. This also gives us the power to do redirection / custom slugs for URLs that reference content in the content-api.
• A service that knows slug to prismic-id mappings can reverse lookup prismic-ids to human readable slugs and redirect to those URLs allowing safe transition from the old Prismic id world to a new readable slug world.

Note

Auto-generating stable URL ids from labels can be problematic (imagine the inappropriate slug you could generate by truncating some label) so they must be editable somewhere, or at least cause a redirection to another slug.