SKDs対象のWeb API設計概論〜Laravelを添えて〜

Transcript

1. SSKDs 対象の Web API 設計概論 SSKDs 対象の Web API 設計概論 ～Laravel を添えて～ arm4
2. 今日、話すこと 今日、話すこと Web API って何？ API を使う人って誰？ RESTful なAPI の設計思想とは？ エンドポイントって何？ SSKDs 対象のWeb API 設計について考えてみよう どういう時にSSKDs 対象のAPI を設計するの？ Laravel での具体的な設計事例 もっと詳しくAPI 設計について知りたい人は？
3. Web API って何？ Web API って何？
4. Web Web World Wide Web の略 ↓ いわゆるインターネット いわゆるインターネット
5. API API Aplication Programming Interface の略 ↓ とある機能を呼び出すための とある機能を呼び出すための インターフェース インターフェース
6. Web API Web API インターネット越しに、 とある機能を呼び出すためのインターフェース
7. インターフェースと言われると難しくて分からな い まずは格ゲーをイメージする。 技が" とある機能" （パンチ、キック） ゲーム機のリモコン+ 操作方法が" インターフェ ース" （A ボタン、B ボタン、AB 同時押しなど） リモコンとテレビをつないでいるケーブルが " インターネット"
8. つまり、 あるURL にアクセスすることで、サーバ側の情報を 取得したり、書き換えたりすることができるも の。 また、その仕様のことをWeb API と呼ぶ。
9. 代表的な API 代表的な API Twitter API Twitter API ツイートの取得などができる。 YouTube API YouTube API YouTube ビデオの情報の取得などができる。 Google Maps Platform Google Maps Platform 地図情報の取得などができる。 https://developer.twitter.com/ https://www.youtube.com/yt/dev/ https://cloud.google.com/maps-platform/
10. API を使う人って誰？ API を使う人って誰？
11. 開発者 = エンジニア = 魔法使い 開発者 = エンジニア = 魔法使い
12. 魔法使いが、呪文『ファイア』を唱えると、炎が モンスターにダメージを与える。 この呪文の『ファイア』がWeb API 。 そして、我々はこれより 『ファイア』 『ケアル』 『ポイゾナ』 などの様々な魔法を創造する" 呪文作るマン" であ り、その作った呪文を使う" 魔法使い" にもなるので ある。
13. 魔法を使う魔法使いの立場に立って 目的 使い勝手 分かりやすさ 統一感 などを考慮する必要がある。
14. 先程紹介した代表的なAPI を例にすると Twitter API は Twitter を操作する呪文作るマンが作 った魔法を、 世界中の魔法使いに使い方を公開し使わせてあげ ている。 ということになる。
15. 世界中の魔法使いに使い方を公開 世界中の魔法使いに使い方を公開 し使わせてあげている？？ し使わせてあげている？？ 俺のシステムは全世界で公開しな 俺のシステムは全世界で公開しな いから API 要らないやん！！ いから API 要らないやん！！
17. 呪文は 俺のシステム専用魔法を俺のシステム内で公開 し、俺や同僚の魔法使いだけが使う場合もある。
18. LSUDs と SSKDs という概念 LSUDs と SSKDs という概念
19. 全世界の魔法使いが使う魔法は、用途も様々であ ることが予想される。 しかし、俺システム専用魔法は、使う人も限られ ていて、用途も限定的である場合が多いだろう。 俺システム専用魔法は汎用的なことよりも、限定 的に特化されているほうが使いやすい場合もあ る。
20. TL;DR TL;DR 使う対象者により設計も変わってくる。
21. LSUDs LSUDs Large set of unknown developers の略。 公開されたWeb API を使う未知の大勢の開発者たち のこと。 SSKDs SSKDs Small set of known developers の略。 非公開・社内用のAPI を使う限定された顔見知りの 開発者たちのこと。
22. 今回お話したいのは、この顔見知りの開発者や俺 が使うためのWeb API をどう設計すればよいのかと いうこと。
23. RESTful な API の設計思想とは？ RESTful な API の設計思想とは？
24. REST API REST API REST の原則に沿った形で設計されたAPI のこと。 一般的に世間に公開されているAPI はREST API と呼 ばれるREST の原則に沿った形で設計されたAPI が多 い。
25. REST REST Representational State Transfer の略。 ネットワーク上のリソースを一意なURI で表し、 そのURI に「GET 」や「POST 」といったHTTP メソッ ドでアクセスすることでデータの送受信を行うと いう設計思想。
26. 要するに？ Method URI Action GET or HEAD users UserController@index POST users UserController@store GET or HEAD users/{user_id} UserController@show PATCH or PUT users/{user_id} UserController@update DELETE users/{user_id} UserController@destroy
27. 要するに？ 処理 操作 一覧取得 登録 CREATE 取得 READ 更新 UPDATE 削除 DELETE
28. 要するに？ CRUD CRUD
29. RESTful なAPI とは、つまり平たく言うと 一意なURI をHTTP メソッドを使い分けることでリソ ースのCRUD 操作を行うAPI 。
30. REST API のメリットは？ REST API のメリットは？ 挙動が分かりやすい 設計が規則的 汎用的
31. REST API の問題点は？ REST API の問題点は？ システムにはCRUD で表現しきれない処理や取得 データもある 様々なリソースのデータを取得or 更新しようと 思うと何度もAPI にアクセスしなければならない
32. TL;DR TL;DR REST は分かりやすく美しい。 しかし、REST にはこだわらずに美しいAPI 設計を考 えたほうがよい。 一般的に公開されているAPI の多くも、そうしてい る。
33. エンドポイントって何？ エンドポイントって何？
34. エンドポイント エンドポイント Web API におけるエンドポイントとは、API にアクセ スするためのURI のこと。 ある目的を達成するためにアクセスするURI のこと をエンドポイントと言う。
35. ユーザ管理 API のエンドポイント ユーザ管理 API のエンドポイント 目的 Method エンドポイント ユーザ一覧 の取得 GET 新規ユーザ 登録 POST ユーザ情報 の取得 GET ユーザの更 新 PUT/PATCH ユーザの削 除 DELETE http://api.example.com/v1/users http://api.example.com/v1/users http://api.example.com/v1/users/{user_id} http://api.example.com/v1/users/{user_id} http://api.example.com/v1/users/{user_id}
36. SSKDs 対象の Web API 設計について SSKDs 対象の Web API 設計について 考えてみよう 考えてみよう
37. 前述だが、 LSUDs 対象に設計するAPI とSSKDs 対象に設計する API では 汎用性よりも専門性が求められる。
38. 例えば、進学塾の新着のお問い合わせ一覧を表示 するページをイメージしてみよう。
39. REST に基づいたAPI 設計にしてしまうと 1 ページを表示するために以下のようなAPI を何度 もコールすることになってしまう。 問い合わせユーザ情報(users/{user_id}) 問い合わせ内容(inquiries/{inquiry_id}) 新着問い合わせ一覧(inquiries?is_new=1) 問い合わせのあった塾情報(schools/{school_id}) ※REST ではリソースの集合を名詞の複数形で表現するのが一般的
40. この問題に対するソリューションとして、 「 1 スクリーン 1API コール、 1 セーブ 1API コール」 という考え方がある。
41. 1 つのページを表示するためにコールする API は 1 回、 1 つの保存をするのにコールする API は 1 回。
42. 新着のお問い合わせ一覧 新着のお問い合わせ一覧 上記ページにアクセスすると 一覧取得API が1 度だけコールされ表示されるとい うのが理想だ。 https://example.com/new_inquiries
43. 新着のお問い合わせ一覧取得エンドポイント 新着のお問い合わせ一覧取得エンドポイント json レスポンス json レスポンス https://example.com/api/new_inquiries { new_inquiries: [ { inquiry_id: 56, message_body: "入塾 検討 資料 送付 school_name: "hoge進学塾", school_id: 3, last_name: "田中", first_name: "太郎", created_at: "2018-08-11 08:20:44", updated_at: "2018-08-11 08:20:44", }, { inquiry_id: 52, message_body: "英語 成績 上 体験授業 希望
44. このエンドポイントは、このページでしか使えな いが 専門性が高いので扱いやすく、分かりやすい。 さらにAPI のリクエスト数も1 度で済むため 表示が速くシステム負荷も少ない。
45. どんな時に SSKDs 対象の API を設計 どんな時に SSKDs 対象の API を設計 するの？ するの？
46. 今までのアプリケーション 今までのアプリケーション 一覧 一覧 クライアントがサーバに一覧ページをリクエスト ↓ サーバでデータを取得＆整形 ↓ 整形したデータをバックエンドのview テンプレー トに渡す ↓ バックエンドで一覧用html を作成 ↓ それをレスポンスとして返す
47. 詳細 詳細 クライアントがサーバに詳細ページをリクエスト ↓ サーバでデータを取得＆整形 ↓ 整形したデータをバックエンドのview テンプレー トに渡す ↓ バックエンドで詳細用html を作成 ↓ それをレスポンスとして返す
48. シングルページアプリケーション シングルページアプリケーション 一覧 一覧 クライアントがサーバに一覧ページをリクエスト ↓ バックエンドのview テンプレートが作成した html の枠をレスポンスとして返す
49. クライアントが一覧取得API をコール ↓ サーバでで一覧データを取得＆整形 ↓ それをjson レスポンスとして返す ↓ 取得したjson を使ってhtml を生成
50. 詳細 詳細 クライアントが詳細取得API をコール ↓ サーバでで詳細データを取得＆整形 ↓ それをjson レスポンスとして返す ↓ 取得したjson を使ってhtml を生成
51. full でページのリソースをリクエストするよりも ajax でapi をコールしてjson を取得するだけのほうが 遥かに通信するデータ量が少なく 表示の切り替えが速い。
53. つまり ajax でデータの取得、保存、更新、削除 ＝ SSKDs 対象のAPI をコール
54. Vue.js を使ってSPA のように構築する場合、 これまでよりもっと、データをjson で返すという API の設計を意識しなければいけない！
55. だって、 サーバへのリクエストは ほぼAPI のコールだけになるから
56. バックエンドがAPI でjson を返すだけになると フロントのhtml とバックエンドのコードが疎結合 になり、いいことがたくさんある。
57. TL;DR TL;DR Q. どんな時にSSKDs 対象のAPI を設計するの？ A. それは君がVue.js でSPA っぽい実装を初めたら
58. Laravel での具体的な設計事例 Laravel での具体的な設計事例
59. ユーザ管理ページで必要な API を考える ユーザ管理ページで必要な API を考える ユーザ一覧の取得 ユーザの検索 ユーザ情報の取得 新規ユーザ登録 ユーザの編集 ユーザの削除 ユーザフォームで使うアカウント権限リスト情 報 ユーザフォームで使う都道府県リスト情報 ※ ユーザ管理ページはSPA 設計でページ遷移はないものとする
60. ユーザの検索は一覧の取得のエンドポイントに パラメータを付与して絞り込みできるようにすれ ば1 つのAPI で済む。 例) https://example.com/users?page=1&keyword= 田 中
61. ユーザ情報の取得は 今回は一覧で取得したデータを 個別ユーザのコンポーネントにセットするため 必要ない。
62. ユーザフォームで使うアカウント権限リスト情 報 ユーザフォームで使う都道府県リスト情報 上記2 点については、 ユーザフォームを表示する際に必要なデータを 取得するAPI としてまとめたほうがいいだろう。 1 スクリーン 1API コールという考え方だ。
63. 必要なエンドポイント 必要なエンドポイント ユーザ一覧の取得＆検索 新規ユーザ登録 ユーザの編集 ユーザの削除 ユーザフォームで使うデータの取得
64. API 設計例 API 設計例 目的 Method URI ユーザ一覧の 取得＆検索 GET api/users 新規ユーザ登録 POST users ユーザの編集 PATCH users/{user_id} ユーザの削除 DELETE users/{user_id} ユーザフォームで 使うデータの取得 GET api/users/form-data
65. web.php web.php Route::middleware(['auth'])->group(function() { Route::prefix('api')->name('api.')->group(function() { Route::prefix('users')->name('users.')->group(function Route::get('/', 'UserController@apiIndex')->name(' Route::get('form-data', 'UserController@apiFormDat }); }); Route::prefix('users')->name('users')->group(function() { Route::get('/', 'UserController@index'); Route::post('/', 'UserController@store')->name('.store Route::patch('/{user}', 'UserController@update')->name Route::delete('/{user}', 'UserController@destroy')->na }); });
66. php artisan route:list php artisan route:list
67. 今回私はRESTful なエンドポイントにはapi というプ リフィックスを付けなかったが 気持ち悪い場合、json を返すアクションには全て api とプリフィックスを付けたほうがいいかもしれ ない。
68. web.php web.php Route::middleware(['auth'])->group(function() { Route::prefix('api')->name('api.')->group(function() { Route::prefix('users')->name('users.')->group(function Route::get('/', 'UserController@apiIndex')->name(' Route::get('form-data', 'UserController@apiFormDat Route::post('/', 'UserController@store')->name('st Route::patch('/{user}', 'UserController@update')-> Route::delete('/{user}', 'UserController@destroy') }); }); Route::prefix('users')->name('users')->group(function() { Route::get('/', 'UserController@index'); }); });
69. php artisan route:list php artisan route:list
70. また、同じアクションに ajax リクエストがあった時のみjson を返す、 もしくはパラメータでjson=1 だった場合のみjson を 返すというように if 分岐するとしてもいいかもしれないが・・・
71. 現状では 現状では api は別アクションにしたほうが 分かりやすいとの結論に至っている。
72. もっと詳しく API 設計について知 もっと詳しく API 設計について知 りたい人は？ りたい人は？
73. 『Web API The Good Parts 』を読もう！ 会社の本棚に置いてあるぜ！