ゼミ内LT「Web API: The Good Parts」 を読みました - I read "Web API: The Good Parts".

Transcript

1. 「Web API: The Good Parts」 を読みました Haruki Tazoe @jdkfx ゼミ内LT
2. ⽥添春樹 広島⼯業⼤学 情報学部 バイクに乗り，読書と映画， ⾳楽を嗜んでます @jdkfx jdkfx 1
3. １Qでやったこと • 『Web API: The Good Parts』の輪読 • ⾳声合成ツール『VOICEVOX』のOSS貢献 • 個⼈ブログのリファクタリング 2
4. Web API: The Good Parts Web APIの設計、開発、運⽤についての解説書。 APIは設計次第で使いづらいものになってしまうだ けでなく公開後の保守運⽤も難しくなってしまいま す。そのためAPIを美しく設計することがとても重 要です。本書では「設計の美しいAPIは、使いやす い、変更しやすい、頑強である、恥ずかしくない」 という考えのもと、APIをどのように設計し運⽤す ればより効果的なのか、ありがちな罠や落とし⽳を 避けるにはどういう点に気をつけなければいけない のかを明らかにします。 3
5. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 4
6. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 5
7. Web APIとはなにか • HTTPプロトコルを利⽤してネットワーク越しに呼び出すAPI • APIとは“Application Programming Interface” • Web APIを美しく設計する重要性 • 設計の美しいWeb APIは使いやすい • 設計の美しいWeb APIは変更しやすい • 設計の美しいWeb APIは頑強である • 設計の美しいWeb APIは（開発者からの⽬線に対して）恥ずかしく ない 6
8. Web APIとはなにか 対象となる開発者の数とAPIの設計思想 • LSUDs（large set of unknown developers）： パブリックにドキュメントを公開し，誰でも登録して使⽤で きるため，誰が使うか分からない さまざまなユースケースを想定してなるべく広く汎⽤的にし なければならない • SSKDs（small set of known developers）： ⾃社のスマートフォンクライアント向けのAPIなど，APIを利 ⽤する開発者が限られる 特定の開発者やその先に存在するエンドユーザーにとって便 利で使いやすいものでなくてはならない 7
9. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 8
10. エンドポイントの設計とリクエストの形 式 • APIのエンドポイントはURIであるから，覚えやすく，どんな 機能を持つURIなのかが⼀⽬でわかるようなURIにする必要が ある • 短く⼊⼒しやすいURI • ⼈間が読んで理解できるURI • ⼤⽂字⼩⽂字が混在していないURI • 改造しやすい（Hackableな）URI • APIのURIが何を⾏いたいのかすぐに考えることができれば， ドキュメントをみなくても開発に注⼒することが可能となる 9
11. エンドポイントの設計とリクエストの形 式 • サーバ側のアーキテクチャが反映されていないURI • http://api.example.com/cgi-bin/get_user.php?user=100 • PHPで書かれていてCGIで動作していることがURIから推測す ることが出来，セキュリティ的にもよろしくない • ルールが統⼀されたURI • ユニークな情報を取得するためのAPIに対して，クエリパラ メータにユニークIDを含めてGETするか，パスにユニークID を含めてGETするかのルールを統⼀するべきである 10
12. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 11
13. レスポンスデータの設計 • データの内部構造をそのAPIを利⽤する際に応じて考える • IDのみを含めたJSONを返す • IDを含めた個⼈の情報を返す • IDに付属する情報をクエリパラメータを使⽤し，レスポンス データとして返す⽅法もある • JSONデータの返し⽅には階層的に返す場合とフラットに返す 場合があり，階層構造で返す場合はJSONのデータサイズが⼤ きくなってしまうため，不要な階層化は避ける 12
14. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 13
15. HTTPの仕様を最⼤限利⽤する • プロキシサーバがオリジンサーバでは変わってしまった情報 を返してしまうことを防ぐ⽅法 • 期限切れモデル： キャッシュの期限が切れたら再度アクセスして情報を取得す る しばらく情報に変動がない者に対して有効である • 検証モデル： 今保持しているキャッシュが最新であるかどうか問い合わせ て，更新されている場合のみ取得を⾏う 情報が常に変動する可能性がある者に対して有効である 14
16. HTTPの仕様を最⼤限利⽤する • クロスオリジンリソース共有（CORS：Cross-Origin Resource Sharing） • リクエスト側でOriginヘッダにアクセス元を指定し，サーバ側 で許可できる⽣成元であればアクセスを許可し，そうでなけ れば403エラーを返す • セキュリティ上，どこから読まれても問題ない場合は Access-Control-Allow-Origin ヘッダに * を指定すると，どこ からでも読み込めることを明⽰することが可能に • 例：GitHubなど 15
17. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 16
18. 設計変更をしやすいWeb APIを作る • APIのバージョンの指定⽅式についての違いなど • パス，クエリ，メディアタイプなどに指定することも可能となって いる • セマンティックバージョニングがバージョニングの⽅法として多く 知られている • クライアントに合わせたアプリケーション向けにインター フェースを変換するオーケストレーション層がサーバに置く 17
19. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 18
20. 堅牢なWeb APIを作る • サーバ・クライアント間での情報の不正⼊⼿ • セッションハイジャックによりセッション情報を盗み，その⼈のID でサービスを利⽤する • 中間者攻撃による危険性もあるため，完全に安全であるとは⾔えな い • HTTPSによるHTTP通信の暗号化により防ぐ • ブラウザでアクセスするAPIにおける問題 • XSS • XSRF • JSONハイジャック 19
21. 堅牢なWeb APIを作る • 悪意のあるアクセスへの対策 • パラメータの改ざんやリクエストの再送信など • セキュリティ対策のためのヘッダやユーザーごとのアクセス を制限する • レートリミットを設け，⼀部のユーザーによる過度のアクセスによ る負荷を防ぐ 20
22. アジェンダ 1. Web APIとはなにか 2. エンドポイントの設計とリクエストの形式 3. レスポンスデータの設計 4. HTTPの仕様を最⼤限利⽤する 5. 設計変更をしやすいWeb APIを作る 6. 堅牢なWeb APIを作る 7. 最後に 21
23. 最後に • 未だにセキュリティについてはまだ分からないことが多いた め関連書籍をもっと読んでみようと思う • 『Webブラウザセキュリティ ― Webアプリケーションの安全 性を⽀える仕組みを整理する』 • 『Real World HTTP 第2版 ―― 歴史とコードに学ぶインター ネットとウェブ技術』 22
24. 質問などありましたらお願いします！ 23
25. 参考⽂献 • Web API: The Good Parts https://www.oreilly.co.jp/books/9784873116860/ 24