Question

我是Laravel（4和5）的新手，最近我正在研究RESTful API。为了允许多个版本的API，我使用URL来确定版本。

我阅读了这篇文章，似乎大多数人都遵循这种方法： How to organize different versioned REST API controllers in Laravel 4?

文件夹结构：

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

在UserController.php文件中，我相应地设置了命名空间：

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');
});

对于版本1，

网址将是简单的http://..../api/v1，对于版本，网址将是http://..../api/v2。这是直截了当的。

我的问题是： 如果我正在构建api的小型升级，比如v1.1，我该如何组织我的文件夹结构呢？我的想法是这样的，它应该仍然没有，因为dot是文件夹的有效名称？

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

另外，我应该如何编写命名空间？这不是像这样的命名空间

namespace Api\v1.1;

我是否可以参考使用＆＃34; dot＆＃34; ？

注意：我不想将其称为版本v2，因为这不是主要升级。

Answer 1

IMO，次要升级不应发布对API的重大更改。所以我的建议是坚持使用整数版本的API。增强功能没有问题，但现有端点应该像往常一样运行。

这样，您的API版本将与路由前缀和命名空间以及测试同步。

示例

您从v1.0开始

你做了一点改动（例如git-tag v1.1），它不会给你的api带来重大变化。开发人员是否需要在代码中执行任何其他操作？不，那里没有。因此，您可以安全地让URI-Prefix保持在V1，以便调用您的api的开发人员无需更改调用您的API的所有代码（因此，自动受益于新的次要版本）。也许你刚刚修复了一个错误，这使得他们的代码表现得像预期的那样，或者你发布了一个新功能，它本身不会破坏现有的功能调用。

您的应用程序不断增长，您发布了包含重大更改的新重新设计的API版本。在这种情况下，您发布新的API-URI前缀（V2）。

请注意，您当然可以在内部跟踪次要版本（例如在SCM中），但开发人员不需要更改所有API调用，只是为了从您发布的小错误修复中受益。无论如何，如果你通知你的客户新的次要版本以及他们提供的错误修正或增强功能（博客，时事通讯，......），那就太好了。

让我补充一点，我不知道任何带有次要API-URL前缀的RESTful API，所以我想这是一种很常见的做法。

Answer 2

您不能使用圆点，而是使用下划线。

但是...

精心设计的api必须在次要版本之间具有BC，因此您不需要为次要更新创建新版本，而是需要编写兼容代码。

Answer 3

我创建了一个简单的Laravel软件包来支持Laravel API版本控制它将回退功能添加到路由。我个人很早以前就需要这样做，但没有意识到使用如此小的程序包就能实现。

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

Laravel RESTful API版本设计

3 个答案: