Recomendados
Mais conteúdo relacionado
Semelhante a RESTful Web API Design
Semelhante a RESTful Web API Design (20)
Mais de Akinari Tsugo
RESTful Web API Design
- 2. 目次 • 基礎編 • RESTfulとは • RESTとは • ROAとは • SOAとは • 実践編 • リクエスト設計 • レスポンス設計
- 3. 基礎編
- 4. “REST”を取り巻く知識として知っておくべきことは何か？ • RESTful とは • REST とは • ROA とは • SOA とは 基礎編の学習目標
- 5. RESTfulとは
- 8. REST とは
- 9. REST とは REpresentational State Transfer
- 11. REST とは REST = Representational State Transfer 2000年 Roy Fielding の博士論文で提唱された 「分散型システムにおける設計原則群」 （参考） https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm └ CHAPTER 5 Representational State Transfer (REST)
- 12. REST制約 • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド
- 13. REST制約 REST原則のみで成立 他の原則、設計思想とは独立 • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド
- 14. REST制約 多層アーキテクチャ Webサービス • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド
- 15. REST制約 ステートレスで 静的なものはキャッシュされる Webサービス • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド
- 16. REST制約 共通の制約を守っている Webサービス • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド
- 17. REST制約 共通の制約を守っている Webサービス • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド • リソースを特定するURI • HTTPメソッドの利用 • メディアタイプ指定 • HATEOAS
- 18. REST制約 共通の制約を守っている Webサービス • nullスタート • クライアント/サーバー • ステートレス • キャッシュ制御 • 統一インターフェース • 階層化システム • コードオンデマンド • リソースを特定するURI • HTTPメソッドの利用 • メディアタイプ指定 • HATEOAS ？
- 19. リソースとは コンピュータ上に格納できる一連のデータ たとえば… • ソフトウェアのバージョン • ブログのエントリ • 猫に関する情報 • 猫の情報が保存されているディレクトリ • 2人の知人同士の関係性
- 20. REST制約（統一インターフェース） すべてのリソースは 一意にアクセス可能な URIを持つ • 統一インターフェース • リソースを特定するURI • HTTPメソッドの利用 • メディアタイプ指定 • HATEOAS
- 21. REST制約（統一インターフェース） リソースに対する操作指定は 適切なHTTPメソッドを使う • 統一インターフェース • リソースを特定するURI • HTTPメソッドの利用 • メディアタイプ指定 • HATEOAS
- 22. REST制約（統一インターフェース） レスポンスは 既知のメディアタイプを指定 • 統一インターフェース • リソースを特定するURI • HTTPメソッドの利用 • メディアタイプ指定 • HATEOAS
- 23. REST制約（統一インターフェース） レスポンスに リソース間のリンクを含める • 統一インターフェース • リソースを特定するURI • HTTPメソッドの利用 • メディアタイプ指定 • HATEOAS Hypermedia As The Engine Of Application State
- 24. RESTを満たす設計 • 多層アーキテクチャ • ステートレス • URIを指定してリソース特定 • HTTPメソッドを利用したリソース操作 • 既知のメディアタイプでレスポンスを返す • リソースをつなぐリンクをレスポンスに含める
- 25. ROAとは
- 26. ROA とは Resource Oriented Architecture
- 28. たとえば… ブログサービス「example-blog.com」の「api」において • ユーザー「tanaka」の「RESTを含む記事」を探す • ユーザー「tanaka」が「新規記事」を投稿する GET http://api.example-blog.com/tanaka/entries?q=REST POST http://api.example-blog.com/tanaka/entries
- 29. SOAとは
- 30. SOA とは Service Oriented Architecture
- 32. たとえば… ブログサービス「example-blog.com」の「api」において • ユーザー「tanaka」の「RESTを含む記事」を探す • ユーザー「tanaka」が「新規記事」を投稿する GET http://api.example-blog.com/tanaka/search?q=REST POST http://api.example-blog.com/tanaka/post
- 33. ① RESTful とは？ ② リソースとは？ ③ RESTを満たすために考慮すべき設計上の制約は？ ④ ROA と SOA の違いは？ 基礎編の確認問題
- 34. 実践編
- 35. RESTful WebAPI を設計するポイントはどんなところにあるか • リクエスト設計 • レスポンス設計 実践編の学習目標
- 36. リクエスト設計
- 37. リクエスト設計 • URIの設計 • HTTPメソッドの適用 • クエリパラメータとパスの使い分け
- 39. URI設計で考慮すること • 短く入力しやすい（冗長なパスを含まない） • 人間が読んで理解できる（省略しない） • 大文字小文字が混在していない（すべて小文字） • 単語はハイフンでつなげる • 単語は複数形を利用する • エンコードを必要とする文字を使わない • サーバー側のアーキテクチャが反映されていない • 改造しやすい（Hackable） • ルールが統一されている
- 40. URI設計で考慮すること • 短く入力しやすい（冗長なパスを含まない） ⇒シンプルで覚えやすいものにすることで入力ミスを防ぐ GET http://api.example.com/service/api/search GET http://api.example.com/search
- 41. URI設計で考慮すること • 人間が読んで理解できる（できるだけ省略しない） ⇒その省略はあなたの自己満足ではない？ 国や文化が変わっても不変な表記にすることで 誤認識を防ぐ GET http://api.example.com/sv/u GET http://api.example.com/users
- 42. URI設計で考慮すること • 大文字小文字が混在していない（すべて小文字） ⇒APIをわかりやすく、間違えにくくするためには統一が必要 統一するなら一般的に小文字 GET http://api.example.com/Users GET http://api.example.com/users
- 43. URI設計で考慮すること • 大文字小文字が混在していない（すべて小文字） ⇒APIをわかりやすく、間違えにくくするためには統一が必要 統一するなら一般的に小文字 GET http://api.example.com/Users GET http://api.example.com/users 理由付けが少し弱いので どちらかと言うと趣味趣向の世界？
- 44. URI設計で考慮すること • 単語はハイフンでつなげる ⇒アンダースコアはタイプライターで下線を引くためのもの ハイフンは単語をつなぐためのもの GET http://api.example.com/popular_users GET http://api.example.com/popular-users
- 45. URI設計で考慮すること • 単語はハイフンでつなげる ⇒アンダースコアはタイプライターで下線を引くためのもの ハイフンは単語をつなぐためのもの GET http://api.example.com/popular_users GET http://api.example.com/users/popular 単語の連結をするくらいなら そもそもURIを見直す
- 46. URI設計で考慮すること • 単語は複数形を利用する ⇒URIで表現しているのは「リソースの集合」 GET http://api.example.com/user/12345 GET http://api.example.com/users/12345
- 47. URI設計で考慮すること • エンコードを必要とする文字を使わない ⇒URIから意味が理解できない GET http://api.example.com/%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%BC GET http://api.example.com/users
- 48. URI設計で考慮すること • サーバー側のアーキテクチャを反映しない ⇒悪意あるユーザーに脆弱性を突かれる危険がある GET http://api.example.com/cgi-bin/get_user.php?id=12345 GET http://api.example.com/users/12345
- 49. URI設計で考慮すること • 改造しやすい（Hackable） ⇒システム依存の設計は意味が理解できない GET http://api.example.com/items/alpha/12345 GET http://api.example.com/items/beta/23456 GET http://api.example.com/items/12345
- 50. URI設計で考慮すること • ルールが統一されている ⇒一定のルールに従って設計することで間違いを防ぐ GET http://api.example.com/friends?id=12345 POST http://api.example.com/friends/12345/message 友達情報取得 メッセージ投稿 GET http://api.example.com/friends/12345 POST http://api.example.com/friends/12345/messages 友達情報取得 メッセージ投稿
- 51. HTTPメソッドとURI URI がリソースを示すのに対し HTTPメソッドはリソースに対する操作を示す GET /v1/users/123 HTTP/1.1 Host: api.example.com 操作 リソース
- 52. HTTP/1.1 メソッド • OPTIONS • GET • HEAD • POST • PUT • DELETE • TRACE • CONNECT
- 53. HTTP/1.1 メソッド（主要なもの） メソッド名 説明 GET リソースの取得 POST リソースの新規登録 PUT 既存リソースの更新 DELETE リソースの削除 HEAD メタ情報の取得
- 54. たとえば… • URIは同じでHTTPメソッドを変えることで操作を変える GET http://api.example.com/users/12345 POST http://api.example.com/users ユーザー情報取得 ユーザーの新規登録 PUT http://api.example.com/users/12345 ユーザーの更新 DELETE http://api.example.com/users/12345 ユーザーの削除
- 55. クエリパラメータとパスの使い分け クエリパラメータとするかどうかの判断基準 • 一意なリソースを表すのに必要かどうか • 省略可能かどうか （例）検索条件（絞り込み条件）はパスに含めない GET http://api.example.com/users?page=3
- 56. レスポンス設計
- 57. レスポンス設計 • データフォーマット • データの内部構造 • エラー表現
- 58. データフォーマット • 以下のいずれかをサポート • XML • JSON • JSONP ※可能ならフォーマット指定できると良い
- 59. データの内部構造 • エンベロープは使わない • 配列ではなくオブジェクトを返す • オブジェクトはできるだけフラットにする • ページネーションをサポートする情報を返す • 日付はRFC3339 （W3C-DTF） 形式を使う • 大きな数値（64bit整数）は文字列で返す
- 60. データの内部構造 • エンベロープは使わない ⇒そもそもHTTPヘッダーが同じ役割 { "header": { "status": "success", "erorCode": 0, }, "response": { ... 実際のデータ ... } }
- 61. データの内部構造 • オブジェクトはできるだけフラットにする ⇒レスポンスの容量を減らす { "id": "12345", "name": "Tsuyoshi Tanaka", "birthday":"3/23", "gender": "male" } { "id": "12345", "name": "Tsuyoshi Tanaka", "profile":{ "birthday":"3/23", "gender": "male" } }
- 62. データの内部構造 • 配列ではなくオブジェクトを返す ⇒JSONインジェクション対策 { "friends": [ { "id": "12345", "name": "Tsuyoshi Tanak" }, { "id": "12345", "name": "Tsuyoshi Tanak" }, ... ] } [ { "id": "12345", "name": "Tsuyoshi Tanaka” }, { "id": "23456", "name": “Kazuma Sato" }, ... ]
- 63. データの内部構造 • ページネーションをサポートする情報を返す ⇒ HATEOAS。REST制約を満たすため。 { "results": [ { "id": "12345", "name": "Tsuyoshi Tanak" }, ... ], "hasNext": true, "nextPage": "/api.example.com/search?page=1" }
- 64. データの内部構造 • 日付はRFC3339 （W3C-DTF） 形式を使う ⇒インターネット上で用いる標準形式 Thu, 29 Mar 2018 08:00:00 GMTRFC822 (RFC1123) Thursday, 29-Mar-2018 08:00:00 GMTRFC850 1521781500Unixタイムスタンプ 2018-03-29T17:00:00+09:00RFC3339 (W3C-DTF)
- 65. データの内部構造 • 大きな数値（64bit整数）は文字列で返す ⇒システムによって扱えない or 誤差が出るケースがある { "id": 123456789012345678 "id_str": "123456789012345678", }
- 66. エラー表現 • ステータスコードで表現する • エラー詳細はレスポンスボディに入れる • エラーの際にHTMLが返らないようにする • サービス閉塞時は503を返し、Retry-Afterをつける
- 67. エラー表現 • ステータスコードで表現する ⇒既にあるものはキチンと使いましょう。 ステータスコード 意味 100番台 情報 200番台 成功 300番台 リダイレクト 400番台 クライアントサイドに起因するエラー 500番台 サーバーサイドに起因するエラー
- 68. エラー表現 • エラー詳細はレスポンスボディに入れる ⇒足りない情報は追加しましょう。 HTTP/1.1 400 Bad Request Server: api.example.com Date: Sun, 25 Mar 2018 01:57:25 GMT Content-Type: application/json; charset=utf-8 { "code": "1234567890" "message": "不正な検索条件です。" }
- 69. エラー表現 • エラーの際にHTMLが返らないようにする ⇒レスポンスフォーマットが変わると クライアントアプリ側で処理できないケースがある HTTP/1.1 404 Not Found Date: Sat, 24 Mar 2018 02:16:54 GMT Server: api.example.com Content-Type: text/html Content-Length: 17707 <!DOCTYPE html> <html lang="ja"> <head> ...
- 70. エラー表現 • サービス閉塞時は503を返し、Retry-Afterをつける ⇒SEO的にこの方法が良い。 クライアント側もいつから再開してよいかわかる。 HTTP/1.1 503 Service Temporary Unavailable Server: api.example.com Date: Sun, 25 Mar 2018 01:57:25 GMT Content-Type: application/json; charset=utf-8 Retry-After: Mon, 2 Apr 2018 01:00:00 GMT { "code": "2345678901" "message" : "現在サービスを利用できません。" }
- 71. 次のリクエストのうち適切な設計のものはどれか？ ① ② ③ ④ 実践編の確認問題 GET http://api.example.com/user/12345 GET http://api.example.com/service/api/search GET http://api.example.com/cgi-bin/get_user.php?id=12345 POST http://api.example.com/users/delete?id=12345 ユーザー情報の削除 ユーザー情報の取得 ユーザー情報の取得 ユーザーの検索
- 72. 次のレスポンスのうち不適切な設計箇所はどこか？ 実践編の確認問題 HTTP/1.1 200 Success Date: Sat, 24 Mar 2018 02:16:54 GMT ... 一部省略 ... { "header": { "status": "success", "erorCode": 1234567890, }, "response": { "id": 123456789012345678, "name": "Tsuyoshi Tanaka", "profile":{ "birthday":"Fri, 29 Mar 1991 09:00:00 GMT", "gender": "male" } } }
- 73. まとめ
- 74. 基礎編 • RESTfulとは 「RESTで求められる原則に従っている」こと • RESTとは 「分散型システムにおける設計原則群」 • ROA とは RESTful インターフェースを備えた リソースごとに設計を行うシステム構築概念 • SOA とは 業務処理ごとに設計を行うシステム構築概念
- 75. 実践編 • リクエスト設計 • URIの設計 • HTTPメソッドの適用 • クエリパラメータとパスの使い分け
- 76. 実践編 • リクエスト設計 • URIの設計 • 短く入力しやすい（冗長なパスを含まない） • 人間が読んで理解できる（省略しない） • 大文字小文字が混在していない（すべて小文字） • 単語はハイフンでつなげる • 単語は複数形を利用する • エンコードを必要とする文字を使わない • サーバー側のアーキテクチャが反映されていない • 改造しやすい（Hackable） • ルールが統一されている • HTTPメソッドの適用 • クエリパラメータとパスの使い分け
- 77. 実践編 • リクエスト設計 • URIの設計 • HTTPメソッドの適用 • GET リソースの取得 • POST リソースの新規登録 • PUT 既存リソースの更新 • DELETE リソースの削除 • HEAD メタ情報の取得 • クエリパラメータとパスの使い分け
- 78. 実践編 • リクエスト設計 • URIの設計 • HTTPメソッドの適用 • クエリパラメータとパスの使い分け • 一意なリソースを表すのに必要かどうか • 省略可能かどうか
- 79. 実践編 • レスポンス設計 • データフォーマット • データの内部構造 • エラー表現
- 80. 実践編 • レスポンス設計 • データフォーマット • XML • JSON • JSONP • データの内部構造 • エラー表現
- 81. 実践編 • レスポンス設計 • データフォーマット • データの内部構造 • エンベロープは使わない • 配列ではなくオブジェクトを返す • オブジェクトはできるだけフラットにする • ページネーションをサポートする情報を返す • 日付はRFC3339 （W3C-DTF） 形式を使う • 大きな数値（64bit整数）は文字列で返す • エラー表現
- 82. 実践編 • レスポンス設計 • データフォーマット • データの内部構造 • エラー表現 • ステータスコードで表現する • エラー詳細はレスポンスボディに入れる • エラーの際にHTMLが返らないようにする • サービス閉塞時は503を返し、Retry-Afterをつける