Laravel RESTful API versioning design

Question

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.

Answer 1

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

1. You begin with v1.0
2. 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.
3. 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 (eg 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.

Answer 2

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.

Answer 3

I created a simple Laravel package to support Laravel API versioning it adds fallback functionality to routes. I personally needed this long ago but didn't realize it will be achieved with such a tiny package.

https://github.com/mbpcoder/laravel-api-versioning