Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Viewers also liked (12)
Similar to REST API のコツ
Similar to REST API のコツ (20)
More from pospome
Recently uploaded
Recently uploaded (7)
REST API のコツ
- 1. REST API のコツ
- 2. 自己紹介 名前 : pospome ブログ : http://d.hatena.ne.jp/pospome/ 職種 : サーバサイドエンジニア
- 3. これは REST API の基礎部分は理解した上で 実装前に見るといいかもしれない資料です
- 6. RESTって URI と HTTPメソッドだけ決めれば いーんじゃないの? このままじゃダメな気がする 自分は REST API を設計できないことを知った
- 9. Web API には大きく分けて2種類ある それが LSUDs と SSKDs どちらを作るのかでAPIの性質が変わる
- 10. LSUDsとは ・Large Set of Unknown Developers ・不特定多数のユーザーに提供するAPI 例：FaceBookAPI, TwitterAPI ・ユーザーの要求に最適化したAPIを 実装することは不可能なので、 データの種類別にエンドポイントを定義する傾向にある
- 12. SSKDsとは ・Small Set of Known Developers ・特定のシステムのみで利用する専用のAPI 例：自社サービス、社内システム ・用途が決まっているので、 データの種類よりも画面別、アクション別に エンドポイントを定義する傾向にある 一般的にAPIというと LSUDs のイメージが強いので、 DBを抽象化したAPIを作りたがる人もいるが、 リソース指向のリソースはDBのテーブル単位とは限らない リソースとは利用者の要求を満たすデータ 1画面の表示に必要なデータの集合体もリソースになる
- 13. SSKDsとは ・1画面1API , 1アクション1API が基本 ボトルネックになる通信回数を最小限にする クライアント側が管理するAPIを最小限にする ただし、無理に1画面1APIにする必要はない サービスの仕様に合ったAPIを実装するのが大事 ・必要な情報が決まっているので、 取得データの細かいオプション指定は不要だが、 クライアントの必要とするデータを 最適化して返す必要がある
- 14. LSUDs を SSKDs に変換する APIサーバを用意するアーキテクチャもある LSUDs API APIサーバ SSKDs API ブラウザ IOS Android
- 18. URI設計
- 19. ・リソースは集合体なので基本的に複数形にする 1つのデータだから単数形、 複数のデータだから複数形ということではなく、 リソースとしての表現を統一する NG test.com/user/100 ←取得するデータは1件 NG test.com/users/ ←取得するデータは複数件 OK test.com/users/100 OK test.com/users/ 扱うリソースが単数に限られる場合は単数にしてもいい
- 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. ・HTTPメソッドで表現できるのであれば、動詞は含めない NG POST test.com/users/add OK POST test.com/users/ GETなど明示的に動詞を含めることで 表現に幅を持たせる事ができるケースもあるので、 動詞を使ってはいけないということではない GET test.com/users/search?name=suzuki&age=20
- 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. ・自分の情報であればid指定ではなく、 self, me というエイリアスを利用できるようにする NG test.com/users/100 OK test.com/users/me エイリアスは便利なだけではなく、 Controllerのエントリーポイントを分けられる 権限周りのバリデーションを分けるたり、 me なのにバリデーションがかかっていないなどの 不具合もパッと見で確認できる エイリアスを利用するには サーバ側でidを特定できる必要がある
- 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}
- 26. APIバージョン
- 28. HATEOS
- 29. HATEOS Hypermedia As The Engine Of Application State リソース同士に関連性のあるAPIのこと
- 30. (´・ω・`) ?
- 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. HATEOSは レスポンスの中に次の動作に必要なAPIを用意する形式 HTMLのようなリンクのあるデータ構造になるので、 クライアント側でAPIの管理をしなくていい JSON に <a> を埋め込むイメージ ＊先ほどのHATEOSの例は簡易的なものです 本当はもっとフィールドが必要です
- 35. APIのレスポンスデータ構造
- 38. ・無駄な階層化を避ける { id:10, name: { last: “lastname”, first: “firstname” } age: 20 } ↓ { id:10, last_name: “lastname”, first_name: “firstname”, age: 20 }
- 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. ・レスポンスのトップレベルにオブジェクト名を付ける 何のデータであるかが分かりやすい [ {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}, ] }
- 42. APIのリクエストデータ構造
- 46. application/json ・個人的に Web API の POST/PUT といえばこれ ・最近はSPAが主流だから 基本こっちを利用すると思うけど、 意外と知らない人が多い印象? ・body部分にJSON形式でデータを格納する ・FWだと get_body().parseJson() とかで パースしてから取得する必要があるかも get_param() 的なやつでは取れない印象
- 48. application/json の方が便利そうだけど、 HTMLのFormを利用するのであれば、 x-www-form-urlencoded の方がいいかもしれない Google, FaceBook, Twitter も 統一されているわけではない
- 49. エラー時のレスポンス
- 53. メンテナンス用のレスポンス
- 55. HTTP Header
- 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. メジャーなAPIで学ぶ
- 58. 自分たちで考えても良いAPIはできない 本を読むことも大切だが、 世の中のAPIがどうなっているのかを知ろう 僕も時間をかけました ただし、 LSUDs と SSKDs では設計方針が違うので、 そのまま流用できるわけではない APIは甘くない 事前に設計方針をすり合わせましょう
- 59. まとめ
- 60. REST API について 過去の僕のように HTTP Method を使って、URIを決めるだけ と思ってませんか? REST API は奥が深い REST API に限らず新しい技術は危険がいっぱい 手に馴染むまでしっかり勉強しましょう
- 61. おわり