I am new to Laravel (4 and 5) and I have recently been working on a RESTful API. In order to allow multiple versions of the API, I am using a URL to determine the version.
It seems most people are following this approach: How to organize different versioned REST API controllers in Laravel 4?
Folders structures:
/app /controllers /Api /v1 /UserController.php /v2 /UserController.php
And in UserController.php
files I set the namespace accordingly:
namespace Api\v1;
or
namespace Api\v2;
and in routes:
Route::group(['prefix' => 'api/v1'], function () { Route::get('user', 'Api\v1\UserController@index'); Route::get('user/{id}', 'Api\v1\UserController@show'); }); Route::group(['prefix' => 'api/v2'], function () { Route::get('user', 'Api\v2\UserController@index'); Route::get('user/{id}', 'Api\v2\UserController@show'); });
The URL will simply be http://..../api/v1
for version 1 and http://..../api/v2
for version 2. This is straightforward.
My questions is:
What if I am building a minor upgrade of the API, say v1.1, how do I organize my folder structure?
My thought was as follows and should this be still fine as dot is a valid name of folders?
/app /controllers /Api /v1 /UserController.php /v1.1 /UserController.php /v1.2 /UserController.php /v2 /UserController.php
Also, how should I write the namespace? There is no namespace like this
namespace Api\v1.1;
Is there a naming convention I can refer to for using "dot" ?
Note: I do not want to call it version v2 because this is not a major upgrade.
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
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.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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With