API Versioning

[Code1110-daktonis]

I plan to use Payload as a headless CMS to deliver content to a Mobile App and in the future to create a website based on it. Now the question came up how to handle breaking changes in the API. We would like to pin the mobile app to a specific version of the API, because we cannot make sure that all users will upgrade their app to a new version immediately. Payload and most other headless CMS do not offer API versioning support out of the box and adding it by hand seems to be rather painful. Now my question is, what is the reason we don't have support for this feature? What are best practices to handle this case? Any help or thoughts would be appreciated.

[matthijs166]

From my experience, the REST API in Payload is very stable and has barely changed since version 1. One of the strengths of Payload is that you stay fully in control of when and how breaking changes happen.

Any breaking change typically comes from your own field setup or collection configuration, which means you can plan these changes deliberately. If you want to evolve a field without introducing a hard break, you can use virtual fields with afterRead hooks to transition smoothly (again, entirely on your terms)

When building more complex applications, you can take this control even further by creating custom endpoints, where you can implement your own versioning strategy. This gives you complete autonomy over how your API evolves. For simple CRUD, this level of customization is usually unnecessary, but the option is always there when you need it.

It’s also a great idea to set up automated tests, so you always know exactly when something changes.