Removal of Bookmarks and Collections in the Prismic Content API

[c0nst4ntin]

These changes will take effect on February 12, 2025:

Removal of Bookmarks:

• Bookmarks, a deprecated feature, will be permanently removed from the /api endpoint.
• This feature was used prior to the introduction of the Single Type and UID field, which now provide better alternatives.

Removal of Collections:

• Collections will no longer appear in the "forms" object in the API responses of the /api endpoint.
• The "forms" object is for Prismic internal use only and will have no impact on our client library (@prismicio/client).
• If you’re using an implementation that is not relying on our JavaScript client, such as requesting directly the first version of our API (/api/v1) or using non-JavaScript clients, we recommend reviewing your implementation and adjusting your code to accommodate this change.

[c0nst4ntin]

@angeloashmore @lihbr So, how do we account for this best in this package? I quickly had a scan through the code:

1. There are two functions, bookmarks(): array and bookmark(string $name) :? string In the Api class for interacting with bookmarks. In the package they are not marked as deprecated, which poses a problem for removing them from the API.

2. Forms are also used with this package. Although I did not fully understand the changes you are going to make to this in the API

How do you think we should proceed here? Let me know what you think!

[lihbr]

Hi @c0nst4ntin, (sorry, I was already off by the time you posted in December, I hope you had nice holidays!)

There are two functions, bookmarks(): array and bookmark(string $name) :? string In the Api class for interacting with bookmarks. In the package they are not marked as deprecated, which poses a problem for removing them from the API.

I think we can mark them as deprecated as of now and let them be until February.

By then, it looks like those functions are only public APIs (not used internally by the PHP kit itself), so we could let them fail gracefully once the Prismic API gets updated, optionally with an explicit error message(?).

From here, maybe this parts needs to be updated to not fail if the bookmarks property is undefined: https://github.com/prismicio-community/php-kit/blob/master/src/Prismic/ApiData.php#L134 (not super familiar with PHP these days, so maybe it already works fine as-is)

Forms are also used with this package. Although I did not fully understand the changes you are going to make to this in the API

Apart from collections, the forms object will not move, so this part should be fine. It was used in the past to know which filters were available on the API mainly.

On the JavaScript side we don't use it anymore in @prismicio/client, apart from telling the tags API endpoint (which is some legacy bit from when we moved tags to their dedicated APIs two years ago).

On the PHP side it looks like this the SearchForm class makes use of it for that purpose. I'm not sure what role it really plays in the PHP kit to be honest, but since the forms property will remain the same you should be fine leaving it as-is.

Voila :) Let me know if I can clarify anything or if you need further information!

[c0nst4ntin]

@lihbr I am also not sure what the SearchForm is used for. As far as I can recall I personally never used the feature. If nothing changes with the prismic api, I would just leave this for now.

Regarding the bookmarks I created a Pull Request (#210) which marks the methods as deprecated and ensures that even without the field in the api response the methods won't throw an exception but rather return an empty array. Do you think this is okay?

[lihbr]

Reviewed, thank you so much :)

[c0nst4ntin]

To sum everything up:

1. Bookmarks are now deprecated (Version 5.4.0) and will be removed from the Prismic API in February (Mark Bookmark Methods as Deprecated (From Discussions #209) #210). They can be removed from the SDK in the next major release.

2. The SearchForm should not be affected by any changes from the API. It will remain in the SDK.

FYI @lihbr

[lihbr]

Beautiful!