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

Transcript

1. SSKDs
   対象の
   Web API
   設計概論
   SSKDs
   対象の
   Web API
   設計概論
   ～Laravel
   を添えて～
   arm4
   

   View Slide

2. 今日、話すこと
   今日、話すこと
   Web API
   って何？
   API
   を使う人って誰？
   RESTful
   なAPI
   の設計思想とは？
   エンドポイントって何？
   SSKDs
   対象のWeb API
   設計について考えてみよう
   どういう時にSSKDs
   対象のAPI
   を設計するの？
   Laravel
   での具体的な設計事例
   もっと詳しくAPI
   設計について知りたい人は？
   

   View Slide

3. Web API
   って何？
   Web API
   って何？
   

   View Slide

4. Web
   Web
   World Wide Web
   の略
   ↓
   いわゆるインターネット
   いわゆるインターネット
   

   View Slide

5. API
   API
   Aplication Programming Interface
   の略
   ↓
   とある機能を呼び出すための
   とある機能を呼び出すための
   インターフェース
   インターフェース
   

   View Slide

6. Web API
   Web API
   インターネット越しに、
   とある機能を呼び出すためのインターフェース
   

   View Slide

7. インターフェースと言われると難しくて分からな
   い
   まずは格ゲーをイメージする。
   技が"
   とある機能"
   （パンチ、キック）
   ゲーム機のリモコン+
   操作方法が"
   インターフェ
   ース"
   （A
   ボタン、B
   ボタン、AB
   同時押しなど）
   リモコンとテレビをつないでいるケーブルが
   "
   インターネット"
   

   View Slide

8. つまり、
   あるURL
   にアクセスすることで、サーバ側の情報を
   取得したり、書き換えたりすることができるも
   の。
   また、その仕様のことをWeb API
   と呼ぶ。
   

   View Slide

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/
   

   View Slide

10. API
    を使う人って誰？
    API
    を使う人って誰？
    

    View Slide

11. 開発者
    =
    エンジニア
    =
    魔法使い
    開発者
    =
    エンジニア
    =
    魔法使い
    

    View Slide

12. 魔法使いが、呪文『ファイア』を唱えると、炎が
    モンスターにダメージを与える。
    この呪文の『ファイア』がWeb API
    。
    そして、我々はこれより
    『ファイア』
    『ケアル』
    『ポイゾナ』
    などの様々な魔法を創造する"
    呪文作るマン"
    であ
    り、その作った呪文を使う"
    魔法使い"
    にもなるので
    ある。
    

    View Slide

13. 魔法を使う魔法使いの立場に立って
    目的
    使い勝手
    分かりやすさ
    統一感
    などを考慮する必要がある。
    

    View Slide

14. 先程紹介した代表的なAPI
    を例にすると
    Twitter API
    は
    Twitter
    を操作する呪文作るマンが作
    った魔法を、
    世界中の魔法使いに使い方を公開し使わせてあげ
    ている。
    ということになる。
    

    View Slide

15. 世界中の魔法使いに使い方を公開
    世界中の魔法使いに使い方を公開
    し使わせてあげている？？
    し使わせてあげている？？
    俺のシステムは全世界で公開しな
    俺のシステムは全世界で公開しな
    いから
    API
    要らないやん！！
    いから
    API
    要らないやん！！
    

    View Slide

16. View Slide

17. 呪文は
    俺のシステム専用魔法を俺のシステム内で公開
    し、俺や同僚の魔法使いだけが使う場合もある。
    

    View Slide

18. LSUDs
    と
    SSKDs
    という概念
    LSUDs
    と
    SSKDs
    という概念
    

    View Slide

19. 全世界の魔法使いが使う魔法は、用途も様々であ
    ることが予想される。
    しかし、俺システム専用魔法は、使う人も限られ
    ていて、用途も限定的である場合が多いだろう。
    俺システム専用魔法は汎用的なことよりも、限定
    的に特化されているほうが使いやすい場合もあ
    る。
    

    View Slide

20. TL;DR
    TL;DR
    使う対象者により設計も変わってくる。
    

    View Slide

21. LSUDs
    LSUDs
    Large set of unknown developers
    の略。
    公開されたWeb API
    を使う未知の大勢の開発者たち
    のこと。
    SSKDs
    SSKDs
    Small set of known developers
    の略。
    非公開・社内用のAPI
    を使う限定された顔見知りの
    開発者たちのこと。
    

    View Slide

22. 今回お話したいのは、この顔見知りの開発者や俺
    が使うためのWeb API
    をどう設計すればよいのかと
    いうこと。
    

    View Slide

23. RESTful
    な
    API
    の設計思想とは？
    RESTful
    な
    API
    の設計思想とは？
    

    View Slide

24. REST API
    REST API
    REST
    の原則に沿った形で設計されたAPI
    のこと。
    一般的に世間に公開されているAPI
    はREST API
    と呼
    ばれるREST
    の原則に沿った形で設計されたAPI
    が多
    い。
    

    View Slide

25. REST
    REST
    Representational State Transfer
    の略。
    ネットワーク上のリソースを一意なURI
    で表し、
    そのURI
    に「GET
    」や「POST
    」といったHTTP
    メソッ
    ドでアクセスすることでデータの送受信を行うと
    いう設計思想。
    

    View Slide

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
    

    View Slide

27. 要するに？
    処理 操作
    一覧取得
    登録 CREATE
    取得 READ
    更新 UPDATE
    削除 DELETE
    

    View Slide

28. 要するに？
    CRUD
    CRUD
    

    View Slide

29. RESTful
    なAPI
    とは、つまり平たく言うと
    一意なURI
    をHTTP
    メソッドを使い分けることでリソ
    ースのCRUD
    操作を行うAPI
    。
    

    View Slide

30. REST API
    のメリットは？
    REST API
    のメリットは？
    挙動が分かりやすい
    設計が規則的
    汎用的
    

    View Slide

31. REST API
    の問題点は？
    REST API
    の問題点は？
    システムにはCRUD
    で表現しきれない処理や取得
    データもある
    様々なリソースのデータを取得or
    更新しようと
    思うと何度もAPI
    にアクセスしなければならない
    

    View Slide

32. TL;DR
    TL;DR
    REST
    は分かりやすく美しい。
    しかし、REST
    にはこだわらずに美しいAPI
    設計を考
    えたほうがよい。
    一般的に公開されているAPI
    の多くも、そうしてい
    る。
    

    View Slide

33. エンドポイントって何？
    エンドポイントって何？
    

    View Slide

34. エンドポイント
    エンドポイント
    Web API
    におけるエンドポイントとは、API
    にアクセ
    スするためのURI
    のこと。
    ある目的を達成するためにアクセスするURI
    のこと
    をエンドポイントと言う。
    

    View Slide

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}
    

    View Slide

36. SSKDs
    対象の
    Web API
    設計について
    SSKDs
    対象の
    Web API
    設計について
    考えてみよう
    考えてみよう
    

    View Slide

37. 前述だが、
    LSUDs
    対象に設計するAPI
    とSSKDs
    対象に設計する
    API
    では
    汎用性よりも専門性が求められる。
    

    View Slide

38. 例えば、進学塾の新着のお問い合わせ一覧を表示
    するページをイメージしてみよう。
    

    View Slide

39. REST
    に基づいたAPI
    設計にしてしまうと
    1
    ページを表示するために以下のようなAPI
    を何度
    もコールすることになってしまう。
    問い合わせユーザ情報(users/{user_id})
    問い合わせ内容(inquiries/{inquiry_id})
    新着問い合わせ一覧(inquiries?is_new=1)
    問い合わせのあった塾情報(schools/{school_id})
    ※REST
    ではリソースの集合を名詞の複数形で表現するのが一般的
    

    View Slide

40. この問題に対するソリューションとして、
    「
    1
    スクリーン
    1API
    コール、
    1
    セーブ
    1API
    コール」
    という考え方がある。
    

    View Slide

41. 1
    つのページを表示するためにコールする
    API
    は
    1
    回、
    1
    つの保存をするのにコールする
    API
    は
    1
    回。
    

    View Slide

42. 新着のお問い合わせ一覧
    新着のお問い合わせ一覧
    上記ページにアクセスすると
    一覧取得API
    が1
    度だけコールされ表示されるとい
    うのが理想だ。
    https://example.com/new_inquiries
    

    View Slide

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: "英語 成績 上 体験授業 希望
    

    View Slide

44. このエンドポイントは、このページでしか使えな
    いが
    専門性が高いので扱いやすく、分かりやすい。
    さらにAPI
    のリクエスト数も1
    度で済むため
    表示が速くシステム負荷も少ない。
    

    View Slide

45. どんな時に
    SSKDs
    対象の
    API
    を設計
    どんな時に
    SSKDs
    対象の
    API
    を設計
    するの？
    するの？
    

    View Slide

46. 今までのアプリケーション
    今までのアプリケーション
    一覧
    一覧
    クライアントがサーバに一覧ページをリクエスト
    ↓
    サーバでデータを取得＆整形
    ↓
    整形したデータをバックエンドのview
    テンプレー
    トに渡す
    ↓
    バックエンドで一覧用html
    を作成
    ↓
    それをレスポンスとして返す
    

    View Slide

47. 詳細
    詳細
    クライアントがサーバに詳細ページをリクエスト
    ↓
    サーバでデータを取得＆整形
    ↓
    整形したデータをバックエンドのview
    テンプレー
    トに渡す
    ↓
    バックエンドで詳細用html
    を作成
    ↓
    それをレスポンスとして返す
    

    View Slide

48. シングルページアプリケーション
    シングルページアプリケーション
    一覧
    一覧
    クライアントがサーバに一覧ページをリクエスト
    ↓
    バックエンドのview
    テンプレートが作成した
    html
    の枠をレスポンスとして返す
    

    View Slide

49. クライアントが一覧取得API
    をコール
    ↓
    サーバでで一覧データを取得＆整形
    ↓
    それをjson
    レスポンスとして返す
    ↓
    取得したjson
    を使ってhtml
    を生成
    

    View Slide

50. 詳細
    詳細
    クライアントが詳細取得API
    をコール
    ↓
    サーバでで詳細データを取得＆整形
    ↓
    それをjson
    レスポンスとして返す
    ↓
    取得したjson
    を使ってhtml
    を生成
    

    View Slide

51. full
    でページのリソースをリクエストするよりも
    ajax
    でapi
    をコールしてjson
    を取得するだけのほうが
    遥かに通信するデータ量が少なく
    表示の切り替えが速い。
    

    View Slide

52. View Slide

53. つまり
    ajax
    でデータの取得、保存、更新、削除
    ＝
    SSKDs
    対象のAPI
    をコール
    

    View Slide

54. Vue.js
    を使ってSPA
    のように構築する場合、
    これまでよりもっと、データをjson
    で返すという
    API
    の設計を意識しなければいけない！
    

    View Slide

55. だって、
    サーバへのリクエストは
    ほぼAPI
    のコールだけになるから
    

    View Slide

56. バックエンドがAPI
    でjson
    を返すだけになると
    フロントのhtml
    とバックエンドのコードが疎結合
    になり、いいことがたくさんある。
    

    View Slide

57. TL;DR
    TL;DR
    Q.
    どんな時にSSKDs
    対象のAPI
    を設計するの？
    A.
    それは君がVue.js
    でSPA
    っぽい実装を初めたら
    

    View Slide

58. Laravel
    での具体的な設計事例
    Laravel
    での具体的な設計事例
    

    View Slide

59. ユーザ管理ページで必要な
    API
    を考える
    ユーザ管理ページで必要な
    API
    を考える
    ユーザ一覧の取得
    ユーザの検索
    ユーザ情報の取得
    新規ユーザ登録
    ユーザの編集
    ユーザの削除
    ユーザフォームで使うアカウント権限リスト情
    報
    ユーザフォームで使う都道府県リスト情報
    ※
    ユーザ管理ページはSPA
    設計でページ遷移はないものとする
    

    View Slide

60. ユーザの検索は一覧の取得のエンドポイントに
    パラメータを付与して絞り込みできるようにすれ
    ば1
    つのAPI
    で済む。
    例) https://example.com/users?page=1&keyword=
    田
    中
    

    View Slide

61. ユーザ情報の取得は
    今回は一覧で取得したデータを
    個別ユーザのコンポーネントにセットするため
    必要ない。
    

    View Slide

62. ユーザフォームで使うアカウント権限リスト情
    報
    ユーザフォームで使う都道府県リスト情報
    上記2
    点については、
    ユーザフォームを表示する際に必要なデータを
    取得するAPI
    としてまとめたほうがいいだろう。
    1
    スクリーン 1API
    コールという考え方だ。
    

    View Slide

63. 必要なエンドポイント
    必要なエンドポイント
    ユーザ一覧の取得＆検索
    新規ユーザ登録
    ユーザの編集
    ユーザの削除
    ユーザフォームで使うデータの取得
    

    View Slide

64. API
    設計例
    API
    設計例
    目的
    Method URI
    ユーザ一覧の
    取得＆検索 GET api/users
    新規ユーザ登録
    POST users
    ユーザの編集
    PATCH users/{user_id}
    ユーザの削除
    DELETE users/{user_id}
    ユーザフォームで
    使うデータの取得 GET api/users/form-data
    

    View Slide

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

    View Slide

66. php artisan route:list
    php artisan route:list
    

    View Slide

67. 今回私はRESTful
    なエンドポイントにはapi
    というプ
    リフィックスを付けなかったが
    気持ち悪い場合、json
    を返すアクションには全て
    api
    とプリフィックスを付けたほうがいいかもしれ
    ない。
    

    View Slide

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

    View Slide

69. php artisan route:list
    php artisan route:list
    

    View Slide

70. また、同じアクションに
    ajax
    リクエストがあった時のみjson
    を返す、
    もしくはパラメータでjson=1
    だった場合のみjson
    を
    返すというように
    if
    分岐するとしてもいいかもしれないが・・・
    

    View Slide

71. 現状では
    現状では
    api
    は別アクションにしたほうが
    分かりやすいとの結論に至っている。
    

    View Slide

72. もっと詳しく
    API
    設計について知
    もっと詳しく
    API
    設計について知
    りたい人は？
    りたい人は？
    

    View Slide

73. 『Web API The Good Parts
    』を読もう！
    会社の本棚に置いてあるぜ！
    

    View Slide