Laravel RESTful API versioning design
IMO, minor upgrades should not publish breaking changes to an API. So my suggestion is to stick to integer versioned APIs. Enhancements are no problems, but existing endpoints should behave as usual.
This way your API-Versions would be in sync with the route-prefixes and the namespaces as well as the tests.
EXAMPLE
- You begin with v1.0
- You make a little change (eg. git-tag v1.1) which does not bring breaking changes to your api. Is there a need for developers to do anything else in their code? No, there is not. So you can safeley let the URI-Prefix stay at
V1, so that developers calling your api do not need to change all their code which is calling your API (and therefore, automatically benefit from the new minor version). Maybe you just fixed a bug, which makes their code behave just as expected or you published a new feature, which by its self does not break existing feature-calls. - Your App grows and you publish new redesigned version of you API which contains breaking changes. In this case, you publish a new API-URI-prefix (
V2).
Be aware that you can of course keep track of the minor versions internally (e.g in SCM), but there should be no need for developers to change all of their API-Calls just to benefit from that little bugfix you published. Anyways, it is nice of course if you notify your clients of the newer minor versions and the bugfixes or enhancements they offer (blog, newsletter, ..)
Let me add, that i am not aware of any RESTful APIs with minor API-URL-prefixes, so i guess this is quite a common practice.
You can not use dots, use underscores instead.
But...
A well-designed api must have BC between minor versions, so you do not need to create new version for minor update, instead you need to write compatible code.