Laravel的RESTful API版本设计 [英] Laravel RESTful API versioning design

问题描述

我是新来的Laravel（4和5），最近我的工作一个RESTful API。
为了让该API的多个版本，我使用的URL来确定的版本。

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.

我跟着读这篇文章，它似乎下面这种方法多数人：
<一href=\"http://stackoverflow.com/questions/16501010/how-to-organize-different-versioned-rest-api-controllers-in-laravel-4\">How组织不同的版本化REST API控制器在Laravel 4？

I read follow this post and it seem most people following this approach: How to organize different versioned REST API controllers in Laravel 4?

文件夹结构：

/app
  /controllers
    /Api
      /v1
        /UserController.php
      /v2
        /UserController.php

而在UserController.php文件，我设置相应的命名空间：

And in UserController.php files I set the namespace accordingly:

namespace Api\v1;

或

namespace Api\v2;

和在路线：

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将是简单的的http：//..../api/v1 1版本的 HTTP：//..../api/v2 获得的版本。这是直截了当。

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

我的问题是：
如果我建立API的小幅度提升，说1.1版，我怎么安排我的文件夹结构？
我的想法是这样，它应该还是罚款点为文件夹的有效名称？

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" ?

请注意：我不想称呼其为V2版，因为这不是一个重大的升级

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

推荐答案

IMO，次要升级不应该公布重大更改到一个API。所以我的建议是坚持整数版本的API。增强功能是没有问题，但现有的端点应该表现如常。

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.

这样，你的API的版本将是同步同为route- prefixes和命名空间以及测试。

This way your API-Versions would be in sync with the route-prefixes and the namespaces as well as the tests.

示例

• 您开始使用V1.0


• 您稍作改动（如git的标签V1.1）不破带来的改变您的API。是否有必要为开发者做任何事情在他们的code？不，那里没有。所以，你可以safeley让URI的preFIX留在 V1 ，以便开发者在调用您的API并不需要改变他们的所有code这是你的呼唤API（因此，自动从次版本中获益）。也许你只是修正了一个错误，这使得正如预期的code的行为，或者您发布的新功能，它通过自身不会破坏现有的功能调用。


• 您的应用程序的增长和发布你的API，它包含了重大更改的新版本重新设计。在这种情况下，你发布一个新的API-URI的preFIX（ V2 ）。

• 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).

请注意，您当然可以跟踪内部的次要版本（例如在SCM），但应该没有必要为开发人员改变他们所有的API通话的只是从您发布的小Bug修复中受益。不管怎么说，这是很好的，当然，如果你通知您的较新的次要版本的客户端和错误修正或改进，它们的价格（博客，通讯，..）

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, ..)

让我补充一点，我不知道有轻微API-URL- prefixes任何RESTful API中的，所以我想这是一个相当普遍的做法。

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.

这篇关于Laravel的RESTful API版本设计的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！