web-dev-qa-db-ja.com

Laravel RESTful APIバージョン管理設計

Laravel（4 and 5）が初めてで、最近RESTful APIに取り組んでいます。APIの複数のバージョンを許可するために、URLを使用してバージョンを判別しています。

私はこの投稿を読んで、ほとんどの人がこのアプローチに従っているようです： 異なるバージョンのREST APIコントローラーを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');
});

URLは単純になります http：//..../api/v1 バージョン1の場合 http：//..../api/v2 バージョンの場合これは簡単です。

私の質問は次のとおりです：APIのマイナーアップグレード、たとえばv1.1をビルドしている場合、フォルダ構造を整理するにはどうすればよいですか？私の考えはこれであり、ドットはフォルダの有効な名前なので、それでも問題ないはずです。

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

また、どのように名前空間を書くべきですか？これはこのような名前空間ではありません

namespace Api\v1.1;

「ドット」を使用するために参照できる命名規則はありますか？

注：これはメジャーアップグレードではないため、バージョンv2として呼び出したくありません。

phpapirestlaravel
37
Sam Wong

IMO、マイナーアップグレードは、APIへの重大な変更を公開しないでください。したがって、私の提案は整数バージョン管理APIに固執することです。機能強化は問題ありませんが、既存のエンドポイントは通常どおりに動作するはずです。

このようにして、APIバージョンはルートプレフィックス、名前空間、およびテストと同期します。

[〜＃〜] example [〜＃〜]

  1. V1.0から始めます
  2. APIに重大な変更をもたらさない小さな変更（たとえば、git-tag v1.1）を行います。開発者がコードで他に何かする必要があるのですか？いいえ、ありません。したがって、URI-PrefixをV1。これにより、APIを呼び出す開発者は、APIを呼び出すコードをすべて変更する必要がなくなります（したがって、自動的に新しいマイナーバージョンの恩恵を受けます）。コードを期待どおりに動作させるバグを修正したか、既存の機能呼び出しを中断しない新しい機能を公開した可能性があります。
  3. アプリが成長し、重大な変更を含むAPIの新しい再設計バージョンを公開します。この場合、新しいAPI-URI-prefix（V2）。

もちろん、マイナーバージョンを内部的に追跡することもできます（SCMなど）が、開発者が公開した小さなバグ修正の恩恵を受けるためだけにAPI呼び出しをすべて変更する必要はないことに注意してください。とにかく、クライアントに新しいマイナーバージョンとそれらが提供するバグ修正または機能拡張（ブログ、ニュースレター、..）を通知するのはもちろん素晴らしいことです。

付け加えておくと、マイナーなAPI-URLプレフィックスを持つRESTful APIには気付いていないので、これは非常に一般的な慣行であると思います。

35
nozzleman

ドットを使用することはできません。代わりにアンダースコアを使用してください。

だが...

適切に設計されたapiには、マイナーバージョン間でBCが必要であるため、マイナーアップデート用に新しいバージョンを作成する必要はなく、代わりに互換性のあるコードを記述する必要があります。

5
aeryaguzov