Laravel RESTful API versioning design

问题:

I am new to Laravel (4 and 5) and recently I am working on a RESTful API. In order to allow multiple version of the API, I am using URL to determine the version.

I read follow this post and it seem most people 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');
});

URL will be simple http://..../api/v1 for version 1 and http://..../api/v2 for version. This is straight forward.

My questions is: What if I am building minor upgrade of api, say v1.1 , how do I organize my folder structure? My thought was this and it should be still fine as dot is 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? This is no namespace like this

namespace Api\v1.1;

Is there naming convention I can refer to for using "dot" ?

Note: I do not want to call it as version v2 because this is not a major upgrade.

回答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 (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.

回答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.