2018-09-26 開催の「第130回 PHP勉強会@東京」におけるLT資料です https://phpstudy.doorkeeper.jp/events/79982

1. API バージョニング を
Laravel で実装するなら
第130回 PHP勉強会＠東京

2. 岡田 正平（おかだ しょうへい）@okashoi
• 株式会社ウィルゲート 2015年新卒入社
• 開発室 ソリューションユニット 所属
• PHP, Laravel, Vue.js
2
自己紹介
Slides:

3. クライアントに対し、古い形式でのアクセス方法を提供しつづける
例）Google Maps Embed API
https://www.google.com/maps/embed/v1/place?q=...&key=...
新しいアクセス方法・レスポンス形式などは v2, v3… としていく
※他にもメディアタイプでバージョンを指定する方法などがある
3
API バージョニング

4. クライアントに対し、古い形式でのアクセス方法を提供しつづける
例）Google Maps Embed API
https://www.google.com/maps/embed/v1/place?q=...&key=...
新しいアクセス方法・レスポンス形式などは v2, v3… としていく
※他にもメディアタイプでバージョンを指定する方法などがある
4
API バージョニング
このスライドではいったん
この方法で考えます

5. 愚直に考えるとこう
routes/api.php
5
Laravel でどう実装する？①
Route::get('v1/posts', 'V1/PostController@index');
Route::get('v2/posts', 'V2/PostController@index');

6. 愚直に考えるとこう
routes/api.php
6
Laravel でどう実装する？①
Route::get('v1/posts', 'V1/PostController@index');
Route::get('v2/posts', 'V2/PostController@index');
バージョンごとに
異なる Controller 明示的に指定

7. たしかに実現できてるけど……
• 新しいバージョンが増えるたびに、全てを追記するの？
➢ バージョンを扱う部分は仕組み化したい
• コントローラを分割してしまうとコピペが横行するおそれアリ
➢ コントローラ内の条件分岐にしたい
7
Laravel でどう実装する？①

8. 8
Laravel でどう実装する？①
参考）http://kenn.hatenablog.com/entry/2014/03/06/105249

9. 改善案：ルーティングパラメータとして渡す
9
Laravel でどう実装する？②
Route::get('{version}/posts', 'PostController@index')
->where('version', 'v[1-9][0-9]*');
routes/api.php
public function index(string $versionString, Request $request)
{
// 'v1' => 1 のように int 値に変換
$version = (int)substr($versionString, 1);
if ($version === 1) {
// v1 の処理
}
// ... 以下略
}
apps/MyApp/Application/Http/Controllers/PostConroller.php

10. 改善案：ルーティングパラメータとして渡す
10
Laravel でどう実装する？②
Route::get('{version}/posts', 'PostController@index')
->where('version', 'v[1-9][0-9]*');
routes/api.php
public function index(string $versionString, Request $request)
{
// 'v1' => 1 のように int 値に変換
$version = (int)substr($versionString, 1);
if ($version === 1) {
// v1 の処理
}
// ... 以下略
}
apps/MyApp/Application/Http/Controllers/PostConroller.php

11. 改善案：ルーティングパラメータとして渡す
11
Laravel でどう実装する？②
Route::get('{version}/posts', 'PostController@index')
->where('version', 'v[1-9][0-9]*');
routes/api.php
public function index(string $versionString, Request $request)
{
// 'v1' => 1 のように int 値に変換
$version = (int)substr($versionString, 1);
if ($version === 1) {
// v1 の処理
}
// ... 以下略
}
apps/MyApp/Application/Http/Controllers/PostConroller.php
パターン指定による制限

12. 改善案：ルーティングパラメータとして渡す
12
Laravel でどう実装する？②
Route::get('{version}/posts', 'PostController@index')
->where('version', 'v[1-9][0-9]*');
routes/api.php
public function index(string $versionString, Request $request)
{
// 'v1' => 1 のように int 値に変換
$version = (int)substr($versionString, 1);
if ($version === 1) {
// v1 の処理
}
// ... 以下略
}
apps/MyApp/Application/Http/Controllers/PostConroller.php

13. ①の問題点は解決できたものの、欲を言うなら
• 毎 action で ←これやるの？
➢ 勝手に変換されていて欲しい
• による制限が に対してできない
➢ パターン指定は一箇所だけにしたい
13
Laravel でどう実装する？②
$version = (int)substr($versionString, 1);
->where() Route::group()
// できそうでできない
Route::group(['prefix' => '{version}'], function () {
Route::get('posts', 'PostController@index');
Route::get('users', 'UserController@index');
})->where('version', 'v[1-9][0-9]*');

15. アイディア：Explicit Route Model Binding を使う
15
Laravel でどう実装する？③
カスタマイズロジックを用いれば Eloquent ORM 以外も Bind できる

16. 1. API バージョンを表現するクラス
（Value Object）を作る
2. RouteServiceProvider で
Binding を（ついでに pattern も）登録
3. Controller で利用する
16
Laravel でどう実装する？③

17. 1. API バージョンを表現するクラス
（Value Object）を作る
2. RouteServiceProvider で
Binding を（ついでに pattern も）登録
3. Controller で利用する
17
Laravel でどう実装する？③
class ApiVersion
{
/**
* @var int
*/
protected $value;
/**
* @param string $versionString
*/
public function __construct(string $versionString)
{
$this->value = (int)substr($versionString, 1);
}
/**
* @return int
*/
public function value(): int
{
return $this->value;
}
/**
* @param int $number
* @return bool
*/
public function is(int $number): bool
{
return $this->value === $number;
}
}

18. 1. API バージョンを表現するクラス
（Value Object）を作る
2. RouteServiceProvider で
Binding を（ついでに pattern も）登録
3. Controller で利用する
18
Laravel でどう実装する？③
public function boot(): void
{
Route::pattern('version', 'v[1-9][0-9]*');
parent::boot();
Route::bind('version', function ($versionString, $route) {
return new ApiVersionValue($versionString);
});
}
tips:
は より前
は より後
でないと正しく動かない
Route::pattern() parent::boot()
Route::bind() parent::boot()

19. 1. API バージョンを表現するクラス
（Value Object）を作る
2. RouteServiceProvider で
Binding を（ついでに pattern も）登録
3. Controller で利用する
19
Laravel でどう実装する？③
Route::get('{version}/posts', 'PostController@index');
public function index(ApiVersion $version, R...
{
// 特定のバージョンかどうか調べるには
// $version->is() を使用
if ($version->is(1)) {
// v1 の処理
}
// バージョンの値を得たければ
// $version->value() を使用
if ($version->value() <= 3) {
// v2, v3 の処理
}
// 以下略
}
↓

20. • Explicit Route Model Binding は Model 以外にも使い道がある！
• API バージョンを Value Object にするは良い工夫だと思う（自画自賛）
• Application Layer の Value Object になる（特殊な例？）
• （余談）そもそも API バージョニングって難しい
20
所感など

21. • 本当にその API にバージョンニングいる？
• SSKDs (Small Set of Known Developers) 向けならいらない？
• c.f.) LSUDs (Large Set of Unknown Developers)
• 後から足すことになるくらいなら、当面 v1 であってもひとまず……
• どのタイミングでバージョンを変える？
• 後方互換が保てなくなったら？時間（1 年ごとなど）で区切る？
• エンドポイント単位で更新？API 全体で更新？
• バージョン指定なしを許容するか？許容する場合の挙動はどうするか？
21
余談：そもそも API バージョニング難しい問題
などなど……