Core: Feature request - Versioning

[soyuka]

It would be nice to add api versioning with a customizable prefix /api/1/ or /myapi/v1/.

Thoughts?

[sroze]

You're right, but how would you want the bundle to manage the versions ? Just by serialising different fields of a class like FOSRest is already doing ? Or something more complicated by serialising different classes ?

My thought is that it would be a cool feature, but when you're starting to versioning an API, it's that you need something more than just some fields difference. Can you explain your real use case and what you want to do with versioning ?

[soyuka]

I think I should do two separated issues here.

First thing is making the prefix customizable: for example if I don't want my api not to be on /api but on /myapi.
Just change the prefix on routing.yml configuration.

Then, api versioning is a big controversal subject (nice link). Versioning can be useful when you have a huge breaking change in your endpoint and when your previous endpoint is still beeing used. It's not really interesting to just choose some fields for a version (like in FOSRest) because we can easily do this with @Groups annotations.

Assuming you have a Product entity. It's linked to a lot of things: orders, suppliers, prices etc. 1 year after, we need to introduce hierarchical data between products and how prices are calculated. Entity will evolve but the default controller won't. For now, we need it to be compatible with the rest of the api. Having a new controller that is called only on a new api version would be a nice solution.

It's not perfect as a real use case, I'll make some more researches on the subject ;).

[dunglas]

A possible solution is to register a new Resource for the new version referencing the same entity class but with other serialization an validation groups then and play with the OperationFactory to have route similar to v1 (currently the name of a resource must be unique).

Not sure if this is a good idea to introduce a feature like versioning in the bundle. It will very difficult to have a generic enough solution. Maybe a cookbook entry with some insights on how to handle such cases will be better.

[eko]

Hello @dunglas,

I've proposed a simple solution here to manage versioning and retro compatibility changes using a X-Accept-Version: 1.1.0 header.

This is in french (sorry ;)) but tutorial + source code is available here: https://codelabs.eleven-labs.com/course/fr/api-versioning-et-retrocompatibilite-avec-symfony/

Do not hesitate if you want me to have a look on how to integrate this solution (which can be easily integrated I think) into API Platform if you are interested.

Elsewhere, no problem guys, everyone can implement its own solution :)