おさらいWebAPI

WebAPIの設計におけるベストプラクティスやRESTとの関係についてまとめて発表した社内勉強会用の資料です

- RESTとは
- エンドポイントのプラクティス
- リクエストヘッダのプラクティス
- ステータスラインのプラクティス
- レスポンスヘッダのプラクティス
- レスポンスボディのプラクティス

Transcript

1. おさらいAPI設計 2021.03.17
2. Yuta Fujii 本資料を作るにあたり参考にしたリソース • Representational State Transfer (REST), Roy Fielding, 2000 • Richardson Maturity Model • REST Resource Naming Guide • HTTP RFC2616 • RESTとRESTfulとRESTishについて • Web API: The Good Parts
3. Yuta Fujii Web APIって HTTPプロトコルを利用して ネットワーク越しに呼び出すAPI Application Programming Interface 中身の動作がわからなくても機能を利用することができるソフトウェアコンポーネントの 外部インターフェイス ・中身の処理の言語 ・データベース設計
4. Yuta Fujii Web APIの構成要素 エンドポイント リクエストライン リクエストヘッダ リクエストボディ ステータスライン レスポンスヘッダ レスポンスボディ
5. その前によく聞くRESTについて
6. Yuta Fujii RESTって CAN’T REST ‘COS PEOPLE ASK ME ABOUT REST SO MUCH
7. Yuta Fujii RESTって 2000 2010
8. Yuta Fujii RESTって
9. Yuta Fujii RESTって RESTであるための6つの制約 1. クライアント・サーバー構成（Client-server architecture） 2. ステートレス（Stateless） 3. キャッシュ可能（Cachability） 4. 単一インターフェイス（Uniform Interface） 5. レイヤードシステム（Layered System） 6. コードオンデマンド（Code-on-demand）
10. Yuta Fujii RESTって
11. Yuta Fujii REST levelという成熟度モデルの導入（2010，Richardson, Martin） Level 0 　XMLでやりとり（The Swamp of POX） Level 1 　リソースの導入（Resources） Level 2 　なるべく正しいHTTP verbを使う （HTTP verb） Level 3 　リソース制御の抽象化（Hypermedia Controls） Level 3まで満たして RESTful RESTって
12. Yuta Fujii REST level Level 0 　XMLでやりとり（The Swamp of POX） Level 1 　リソースの導入（Resources） Level 2 　なるべく正しいHTTP verbを使う （HTTP verb） Level 3 　リソース制御の抽象化（Hypermedia Controls）←これがしんどい RESTfulは大変
13. Yuta Fujii RESTfulは大変 Level 3 　リソース制御の抽象化（Hypermedia Controls） レスポンスに，その次に想定される処理のエンドポイントをHypertextで記述 • クライアントがエンドポイントの変更の影響を受けない
14. Yuta Fujii RESTfulは大変 レスポンスに，その次に想定される処理のエンドポイントをHypertextで記述
15. 構成要素ベストプラクティス
16. エンドポイント リクエストライン リクエストヘッダ リクエストボディ ステータスライン レスポンスヘッダ レスポンスボディ
17. Yuta Fujii エンドポイント URI基本編 - Consistency is the key • 短く入力しやすい • 人間が読んで理解できる • 大文字小文字が混在していない • 改造しやすい • _ ではなく - を使う • バージョンを含んでOK
18. Yuta Fujii エンドポイント RESTful編 • リソースは名詞複数形 • DB schemaのテーブル名に合わせる必要はない • 手続きに関する処理は動詞でも構わないとされる
19. Yuta Fujii エンドポイント｜HTTP verb RESTful編 • 適切なHTTP verbを用いる（Level 2） Best Practice編 • 適切なHTTP verbを用いる ◦ XSRF対策 • メソッドオーバーライド ◦ X-HTTP-Method-Overrideヘッダ ◦ _methodパラーメータ
20. エンドポイント リクエストライン リクエストヘッダ リクエストボディ ステータスライン レスポンスヘッダ レスポンスボディ
21. Yuta Fujii RESTful編 • 認証情報はヘッダでもOK（Stateless） ◦ URIに載せても，bodyでも良い Best Practice編 • 必要に応じてX-HTTP-Method-Overrideヘッダ リクエスト｜request header
22. エンドポイント リクエストライン リクエストヘッダ リクエストボディ ステータスライン レスポンスヘッダ レスポンスボディ
23. Yuta Fujii RESTful編 • Cache-Controlヘッダは入れる（Cachability） • Content-Typeヘッダは入れる ◦ トップレベルはapplications/ が主流 ◦ 独自タイプは “application/x-mytype” “x-”で始めるのは古い．ドットで繋ぐ（ application/vnd.companyname.awesomeformat ） レスポンス｜response header
24. Yuta Fujii レスポンス｜response header Best Practice編 • Content-Typeヘッダは入れる • X-Content-Type-Options: nosniff • 独自のヘッダは “x-”接頭辞 ◦ 必ずつける必要はない
25. Yuta Fujii レスポンス｜response header
26. エンドポイント リクエストライン リクエストヘッダ リクエストボディ ステータスライン レスポンスヘッダ レスポンスボディ
27. Yuta Fujii レスポンス｜response body Best Practice編 • エンベロープは冗長なので避ける ◦ メタ情報はHeader • 配列返却のときも最上位はオブジェクトで返す ◦ JSONインジェクションリスクを回避できる • エラーはステータスコードで表現する ◦ 詳細はbodyで記述する ◦ 実際にはエラーも200OKで返るAPIも．．．
28. Yuta Fujii レスポンス｜response body
29. エンドポイント リクエストライン リクエストヘッダ リクエストボディ ステータスライン レスポンスヘッダ レスポンスボディ
30. Yuta Fujii ステータスコード 200 OK
31. Yuta Fujii ステータスコード 201 Created
32. Yuta Fujii ステータスコード 202
33. Yuta Fujii ステータスコード 202 Accepted リクエスト処理は受理したが完了していないことを示す リクエスト処理を非同期で行う場合に，利用される
34. Yuta Fujii 301 Moved Permanently ステータスコード コンテンツは永久に移転 HTTP verbの変更は許可（POSTで受けた時にGETでredirectしてよい）
35. Yuta Fujii 302 Found ステータスコード コンテンツは一時的に移転 HTTP verbの変更は許可（POSTで受けた時にGETでredirectしてよい）
36. Yuta Fujii ステータスコード 304
37. Yuta Fujii 304 Not Modified ステータスコード 前回のリクエストからコンテンツは変更がない Bodyは空 キャッシュのValidation Modelで利用される
38. Yuta Fujii 400 Bad Request ステータスコード
39. Yuta Fujii 401 Unauthorized ステータスコード 認証エラー
40. Yuta Fujii 402 Payment Required ステータスコード The 402 (Payment Required) status code is reserved for future use.
41. Yuta Fujii 403 Forbidden ステータスコード 認可エラー
42. Yuta Fujii 404 Not Found ステータスコード 何が存在しなかったのかを説明るすことが大事 対象リソースが存在しなかったのか，存在しないエンドポイントだったのか
43. Yuta Fujii 405 Method Not Allowed ステータスコード
44. Yuta Fujii 406 Not Acceptable ステータスコード クライアントが指定したデータ形式にAPIが対応していない
45. Yuta Fujii 408 Request Timeout ステータスコード
46. Yuta Fujii 409 Conflict ステータスコード リソースのコンフリクト
47. Yuta Fujii 410 Gone ステータスコード あったけど，今はない 「あったけど」が管理できている必要がある 個人情報系には不向き（あったけど，を知らせる必要がない）
48. Yuta Fujii 414 Request-URI Too Long ステータスコード
49. Yuta Fujii 429 Too Many Requests ステータスコード
50. Yuta Fujii 500 Internal Server Error ステータスコード
51. Yuta Fujii 502 Bad Gateway ステータスコード
52. Yuta Fujii 503 Service Unavailable ステータスコード メンテナンスで一時的に利用できない時は503と Retry-Afterヘッダを活用しよう
53. Yuta Fujii 504 Gateway Timeout ステータスコード
54. Yuta Fujii ステータスコード｜Rails rails/actionpack/lib/action_dispatch/middleware/exception_wrapper.rb
55. Yuta Fujii おわりに セキュリティ編 • TBC 改良点はどこにあるか？？→
56. THANK YOU.