Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

REST API のコツ

26,782 views

Published on

社内勉強会向け資料

Published in: Technology
  • Be the first to comment

REST API のコツ

  1. 1. REST API のコツ
  2. 2. 自己紹介 名前 : pospome ブログ : http://d.hatena.ne.jp/pospome/ 職種 : サーバサイドエンジニア
  3. 3. これは REST API の基礎部分は理解した上で 実装前に見るといいかもしれない資料です
  4. 4. なぜ勉強しようと思ったのか?
  5. 5. 半年ほど某有名APIを触る機会があった そのAPIは(当然ながら)設計に一貫性があり 自分の作る変なAPIとは大違いだった
  6. 6. RESTって URI と HTTPメソッドだけ決めれば いーんじゃないの? このままじゃダメな気がする 自分は REST API を設計できないことを知った
  7. 7. ということで、コツを紹介していきます
  8. 8. LSUDs / SSKDs
  9. 9. Web API には大きく分けて2種類ある それが LSUDs と SSKDs どちらを作るのかでAPIの性質が変わる
  10. 10. LSUDsとは ・Large Set of Unknown Developers ・不特定多数のユーザーに提供するAPI  例:FaceBookAPI, TwitterAPI ・ユーザーの要求に最適化したAPIを  実装することは不可能なので、  データの種類別にエンドポイントを定義する傾向にある
  11. 11. LSUDsとは ・最適化は不可能だが、  最低限の要求には応えられるように  細かいオプションを用意したAPIになっていたり、  APIの数が多い  例:フィールド指定、ソート指定 ・APIへのアクセス数を減らし、利便性を上げるために  関連するデータを一緒に返すことも考える  最適化できないながらも  ユーザーのユースケースに寄せた設計にする
  12. 12. SSKDsとは ・Small Set of Known Developers ・特定のシステムのみで利用する専用のAPI  例:自社サービス、社内システム ・用途が決まっているので、  データの種類よりも画面別、アクション別に  エンドポイントを定義する傾向にある  一般的にAPIというと LSUDs のイメージが強いので、  DBを抽象化したAPIを作りたがる人もいるが、  リソース指向のリソースはDBのテーブル単位とは限らない  リソースとは利用者の要求を満たすデータ   1画面の表示に必要なデータの集合体もリソースになる
  13. 13. SSKDsとは ・1画面1API , 1アクション1API が基本  ボトルネックになる通信回数を最小限にする  クライアント側が管理するAPIを最小限にする  ただし、無理に1画面1APIにする必要はない  サービスの仕様に合ったAPIを実装するのが大事 ・必要な情報が決まっているので、  取得データの細かいオプション指定は不要だが、  クライアントの必要とするデータを  最適化して返す必要がある
  14. 14. LSUDs を SSKDs に変換する APIサーバを用意するアーキテクチャもある LSUDs API APIサーバ SSKDs API ブラウザ IOS Android
  15. 15. DBのデータ構造をそのまま返すAPIはNG クライアントのために DBを抽象化しなければならない クライアントが使いやすいAPIを心がけよう サーバサイドの基本は受け身 どちらを選択してエンドポイントを 設計するかが最初の1歩になる
  16. 16. SSKDs は自分たち専用であり、 LSUDs を参考にできない部分があるので、 オレオレ仕様になりがち 「チームで共通の認識を持てればいい」 「ドキュメントあるからそれを見ればいい」 ↑ こういう会話が出てくると危ない 正しい設計を見失ってる兆候
  17. 17. 変な設計にしてしまうと ドキュメント更新が止まった時に困ったり・・・ 毎回口頭で説明することになったり・・ 色々と面倒です 事前にちゃんと設計しておくことが大事
  18. 18. URI設計
  19. 19. ・リソースは集合体なので基本的に複数形にする  1つのデータだから単数形、  複数のデータだから複数形ということではなく、  リソースとしての表現を統一する  NG test.com/user/100 ←取得するデータは1件  NG test.com/users/   ←取得するデータは複数件  OK test.com/users/100  OK test.com/users/  扱うリソースが単数に限られる場合は単数にしてもいい
  20. 20. ・リソースは可能な限りパスで表現する  NG test.com/users/   ←一覧を返す  NG test.com/users/100 ←指定されたidで返す  OK test.com/users/list  OK test.com/users/(detail)/100    単語を繋げる場合はパスとして表現できないかを検討する  NG test.com/latest_users_list  OK test.com/users/list/latest
  21. 21. ・HTTPメソッドで表現できるのであれば、動詞は含めない  NG POST test.com/users/add  OK POST test.com/users/  GETなど明示的に動詞を含めることで  表現に幅を持たせる事ができるケースもあるので、  動詞を使ってはいけないということではない  GET test.com/users/search?name=suzuki&age=20
  22. 22. ・オプションはパスではなくクエリパラメータにする  NG test.com/users/3  OK test.com/users?page=3 ・Viewがある場合はAPIであることを明示する  ViewなのかAPIなのかを明示しないと管理しにくい  NG test.com/users/100  OK test.com/api/users/100  OK api.test.com/users/100
  23. 23. ・自分の情報であればid指定ではなく、  self, me というエイリアスを利用できるようにする  NG test.com/users/100  OK test.com/users/me  エイリアスは便利なだけではなく、  Controllerのエントリーポイントを分けられる  権限周りのバリデーションを分けるたり、  me なのにバリデーションがかかっていないなどの  不具合もパッと見で確認できる  エイリアスを利用するには  サーバ側でidを特定できる必要がある  
  24. 24. 個人的な実装になってしまいますが、 SSKDs の場合には以下の様なURIにすることが多いです 【HTMLを表示するためのURI】 GET test.com/users/ 【画面表示用API】 GET test.com/api/v1/view/movie_list GET test.com/api/v1/view/movie_detail/{id} GET test.com/api/v1/view/common/header 【Action用API】 POST test.com/api/v1/action/movie/ PUT test.com/api/v1/action/movie/{id} DELETE test.com/api/v1/action/movie/{id}
  25. 25. 有名どころのAPIでも違いがあったりするので、 どれかに寄せて作ると一貫性があって、 きれいなAPIになる URI設計については このスライドの説明を真に受けてはいけない 一貫性が大事
  26. 26. APIバージョン
  27. 27. APIにバージョンを持たせることで クライアント側で利用するAPIを任意に選択できる サーバのAPI変更作業にクライアントが引っ張られない バージョンアップのタイミングでリファクタリングが可能 後方互換を保とう test.com/v1/users/list test.com/v2/users/list URIではなく、 HTTPヘッダーに指定されたバージョンを元に ルーティングする方法もある
  28. 28. HATEOS
  29. 29. HATEOS Hypermedia As The Engine Of Application State リソース同士に関連性のあるAPIのこと
  30. 30. (´・ω・`) ?
  31. 31. 以下はAPIのレスポンスです 一応JSONっぽく書いてます { users:{ { id:1, name:'sato' }, { id:2, name:'suzuki' }, } }
  32. 32. HATEOSにしました { users:{ { id:1, name:'sato', link: { href: “http://api.test.com/users/1” } }, { id:2, name:'suzuki', ink: { href: “http://api.test.com/users/2” } }, } }
  33. 33. HATEOSは レスポンスの中に次の動作に必要なAPIを用意する形式 HTMLのようなリンクのあるデータ構造になるので、 クライアント側でAPIの管理をしなくていい JSON に <a> を埋め込むイメージ *先ほどのHATEOSの例は簡易的なものです 本当はもっとフィールドが必要です
  34. 34. 【HATEOSのメリット】 ・APIのURI変更がサーバサイドで完結する ・クライアントがAPIを管理しなくていい 【HATEOSのデメリット】 ・採用事例があまりない気がする ・送信するデータ量が多くなる ・サーバサイドがデータの関連性を意識する必要がある  SSKDsだと画面遷移を意識する必要もあるので、  画面側の仕様変更が実装に影響しやすくなる
  35. 35. APIのレスポンスデータ構造
  36. 36. すでに規格が存在する ・JSON-RPC ・HAL ・JSON API ・Collection+JSON これらを検討してもいいし、 自分で定義してもいい とりあえず、ググるといいかも
  37. 37. レスポンスデータのコツ ・DBから取得したデータはクライアント用に加工して返す  クライアントにとって最適なレスポンスを提供する ・DBのカラム名とレスポンスのフィールド名は  同じである必要はない  クライアント側にとって自然なフィールド名にする
  38. 38. ・無駄な階層化を避ける { id:10, name: { last: “lastname”, first: “firstname” } age: 20 } ↓ { id:10, last_name: “lastname”, first_name: “firstname”, age: 20 }
  39. 39. ・似たようなデータ構造は階層にしてもいい { my_last_name: “lastname”, my_first_name: “firstname”, friend_last_name: “lastname”, friend_first_name: “firstname”, } ↓ { me: { last_name: “lastname”, first_name: “firstname”, }, friend:{ last_name: “lastname”, first_name: “firstname”, } }
  40. 40. ・レスポンスのトップレベルにオブジェクト名を付ける  何のデータであるかが分かりやすい [ {id:10, score:10}, {id:11, score:11}, {id:12, score:12}, ] ↓ { users:[ {id:10, score:10}, {id:11, score:11}, {id:12, score:12}, ] }
  41. 41. サーバ側がレスポンスを利用することはないので クライアントの要望に沿った構造にするのが基本
  42. 42. APIのリクエストデータ構造
  43. 43. リクエストについては レスポンス構造ほど考える必要はないので、 そんなに悩むこともないはず どのようなデータを渡すかくらいだと思う
  44. 44. POST/PUT で利用する content-type だけ抑えておこう application/x-www-form-urlencoded or application/json
  45. 45. application/x-www-form-urlencoded ・HTMLのForm送信 ・一般的なイメージはこれかも ・body部分に  key=value&key=value の形式で  データを格納する ・FWだと get_param(“key”) とかで取得できる
  46. 46. application/json ・個人的に Web API の POST/PUT といえばこれ ・最近はSPAが主流だから  基本こっちを利用すると思うけど、  意外と知らない人が多い印象? ・body部分にJSON形式でデータを格納する ・FWだと get_body().parseJson() とかで  パースしてから取得する必要があるかも  get_param() 的なやつでは取れない印象
  47. 47. application/json ・Form形式とは違い、  データをネストさせることができるので、  柔軟なデータ表現が可能になる  複雑なデータ構造を扱うならこれがいい ・レスポンスデータと同じように  JSON Schema で管理できる ・レスポンスがJSONならリクエストもJSONなのでは?  という自然な発想
  48. 48. application/json の方が便利そうだけど、 HTMLのFormを利用するのであれば、 x-www-form-urlencoded の方がいいかもしれない Google, FaceBook, Twitter も 統一されているわけではない
  49. 49. エラー時のレスポンス
  50. 50. 大体以下が必要になる ・システムのエラーコード  お問い合わせ対策&クライアント側のメッセージ出し分け  変に細かくすると管理が大変  ざっくりし過ぎると意味が無い ・開発者用のエラーメッセージ  本番環境では出力しないでおくといい   ・エラーに対するドキュメントのリンク  普通に面倒なので SSKDs では不要だと思う
  51. 51. ・ユーザー用のエラーメッセージ  ある程度抽象的なデフォルトメッセージは  サーバで管理し、  必要に応じてクライアント側で上書きするのが望ましい
  52. 52. サーバ側では 「システムエラーです」 「データが存在しません」 的な抽象的なメッセージとエラーコードを返す クライアント側では エラーコードと表示している画面によって、 「データが存在しません」を 「フレンドが存在しません。一度画面を更新してからもう一度操 作してください」 のようなユーザーに優しいものに書き換える エラーコードって結構強力
  53. 53. メンテナンス用のレスポンス
  54. 54. メンテ用のエラーレスポンスを作っておくと便利 ・メンテ用のエラーコード  503でもいいけどエラーコードが必要な場合は  用意しておく ・メンテ文言   ・メンテ開始、終了時間 ・ただ、なくてもなんとかなるので、どーでもいいかも
  55. 55. HTTP Header
  56. 56. HTTP Header の設定には便利なものが多い 普段は見ないところにも気を配ろう ・Expire ・Etag, Last-Modified ・Cache-Control ・Content-Type ・Accept ・Content-Security-Policy ・X-Frame-Options ・X-XSS-Protection アプリケーショントークンのような固定値は Headerに設定できるようにすると APIの利便性が向上することもある HTTPの URI, Body だけではなく、Header も上手く使おう
  57. 57. メジャーなAPIで学ぶ
  58. 58. 自分たちで考えても良いAPIはできない 本を読むことも大切だが、 世の中のAPIがどうなっているのかを知ろう 僕も時間をかけました ただし、 LSUDs と SSKDs では設計方針が違うので、 そのまま流用できるわけではない APIは甘くない 事前に設計方針をすり合わせましょう
  59. 59. まとめ
  60. 60. REST API について 過去の僕のように HTTP Method を使って、URIを決めるだけ と思ってませんか? REST API は奥が深い REST API に限らず新しい技術は危険がいっぱい 手に馴染むまでしっかり勉強しましょう
  61. 61. おわり

×