美しいWebAPIの作り方.pdf

研究室の本紹介プレゼンで発表したスライドです

Transcript

1. KatLab 片山徹郎研究室 平成30年9月14日(金) 平木場 風太 紹介 Web API T h e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~
2. 背景1 2 家計簿サービスを作ったぞ！ いろんな人に使ってもらいたいな〜
3. 背景2 3 そうだ！ WebAPIを作ってプログラマ達の力 を借りよう！！ プログラマ軍団
4. 背景3 4 でもWebAPIの設計ってどうやんの？ HTTPもサーバもわかるけど… うおっ
5. アジェンダ 1. 背景 2. WebAPIとは 3. 紹介する本の概要 4. 美しいWebAPIを作るには 5
6. 6 美しいWebAPIの作り方 WebAPIの概要 まずはWebAPIを おさらいしよう！
7. WebAPIとは • HTTPプロトコルを利用してネットワーク越し に呼び出すAPI(Application Programming Interface)のこと • あるURIにアクセスすることで、サーバ側の情 報を書き換えたり、サーバ側に置かれた情報を 取得できたりすることができるWebシステム。 • プログラムからサービスに容易にアクセスでき る。 7
8. 実際にWebAPIを利用してみる 利用API：鯖江市コミュニティバス（つつじバス） ⚫ 福井県鯖江市で運行しているバス。 ⚫ 時刻表、バス停、走行中バスの座標や、運行情報等をWebAPIとして提供して いる。 ⚫ http://www.city.sabae.fukui.jp/users/tutujibus/web-api/web-api.html 8
9. “運行状況に関するお知らせ” を確認する ← APIの使い方。 エンドポイント、リ クエストパラメータ、 レスポンスを確認し ておく。 ↓ ブラウザで利用。 (全てのAPIがブラウザで利用できるわけではない) 9
10. 10 美しいWebAPIの作り方 Web API The Good Parts の概要 この本は何？？
11. 紹介する本 Web API: The Good Parts • 著者: 水野 貴明 • 発行月: 2014年11月 • ISBN: 978-4-87311-686-0 • 出版社: オライリージャパン Web APIの設計、開発、運用に ついての解説書。 XML over HTTP方式、JSON over HTTP方式を扱う。 11
12. 各章の概要1 1章 Web APIとは何か → WebAPIを取り巻く現状と本書の内容の活かし方など。 2章 エンドポイントの設計とリクエストの形式 →クライアントからサーバに対して行うアクセスの設計など。 3章 レスポンスデータの設計 →リクエストに対して返されるレスポンスデータの構造の設 計など。 12
13. 各章の概要2 4章 HTTPの仕様を最大限利用する(省略) → HTTPの仕様をどのようにAPIに反映させるべきか。 5章 設計変更をしやすいWeb APIを作る(省略) → 公開したAPIを安全に修正する方法。 6章 堅牢なWebAPIを作る(省略) → 想定しないアクセスによる影響を最小限に抑えるた めのセキュリティや安定性。 13
14. 各章の概要3 付録A WebAPIを公開する際にできること → WebAPIにおいて、考慮すべき設計以外の事柄の紹介。 付録B WebAPIチェックリスト → 本書で触れた内容をきちんと設計に反映できている かを簡単にチェックするための一覧表。 14
15. APIを公開するということ APIを公開することでさまざまな付加価値 を他の企業や個人が提供してくれる。 サービスの価値や情報の質が向上する可 能性がある！ 15 したがって
16. 例えば家計簿サービスを公開する 16 開発者 ユーザ 家計簿サービス WebAPI サードパーティ開発者 家計簿アプリ 家計簿ブラウザ拡張機能 サービス価値の向上
17. WebAPIを美しく設計しよう しかし、先の例は美しいWebAPIである場合！ 17 美しくないWebAPI 美しいWebAPI したがって、 WebAPIを美しく設計することが大事
18. 設計の美しいWebAPIとは？ 美しいAPI設計の“美しい”とは • よく考えられている • わかりやすく整理されている • 無駄がないなどの完成度の高さ 18 設計の“美しい”WebAPIは • 使いやすい - サードパーティ開発者の負担軽減 • 変更しやすい - 利用者に影響ない変更が可能 • 頑強である - 不正利用の防止、ダウンタイム低減 • 恥ずかしくない - サービス開発者の技術レベルを誇示
19. 美しいWebAPIを作る際の重要な原則 本書の思想の根幹をなす重要な原則 • 標準仕様が決まっているものに関しては仕様に従う • 標準仕様が存在していないものに関してはデファ クトスタンダードに従う すでにあるルールに従うことで、開発したAPIを利 用者が容易に利用できたり、既存のクライアントラ イブラリの流用が可能になったりする。 → エコシステムの拡大 19
20. 20 美しいWebAPIの作り方 エンドポイントの 設計 入口はわかりやすい方が 良い！！
21. 重要な原則 APIにアクセスするためのURI 例) ToDoリストでユーザ情報を取得するAPIのエンドポイント → https://api.example.com/v1/users/me 21 原則 覚えやすく、 どんな機能を持つURIなのかがひと目でわかる エンドポイント
22. 守るべき項目1 • 短く入力しやすいURI 悪い例 http://api.example.com/service/api/search 良い例 http://api.example.com/search • 大文字小文字が混在していないURI 悪い例 http://api.example.com/Users/12345 良い例 http://api.example.com/users/12345 • サーバ側のアーキテクチャが反映されていないURI 悪い例 http://api.example.com/cgi-bin/get_user.php?user=100 このURIを見るだけで、このAPIが恐らくPHPで書かれていてCGIとして動作し て ることがわかる。 22
23. 守るべき項目2 23 • 人間が読んで理解できるURI 悪い例 http://api.example.com/sv/u/ • 改造しやすい(Hackebleな)URI 悪い例 • ルールが統一されたURI 悪い例 友達の情報を取得するAPI http://api.example.com/friend?id=100 メッセージの投稿 http://api.example.com/friend/100/message
24. HTTPメソッドに合わせた処理をする1 24 HTTPでのアクセス時に指定する命令。 例) GET /v1/users/123 HTTP/1.1 Host: api.example.com HTTPメソッド
25. HTTPメソッドに合わせた処理をする2 それぞれの目的に応じて適切にメソッドを使い分ける 25
26. 26 美しいWebAPIの作り方 レスポンスデータ の設計 プログラムに優しい手紙 を書こう！
27. データフォーマット レスポンスデータでどういったデータフォーマット （構造化データの表現方法）を採用するかを決める。 27 JSONをデフォルトとして対応し、 必要があればXMLにも対応する！ JavaScript Object Notationの略。 ポピュラー。 JSON Extensible Markup Languageの 略。昔はポピュラー。 XML
28. 階層的 or フラット？ 同じデータでも、フラットに表すことも階層的に表す こともできる。どちらにすべきだろうか？ 上の例の場合、senderとreceiverのようにどちらも同じ ユーザという構造を表しているので、階層構造で表現 した方が良いと言える。 28 階層的に表す場合 フラットに表す場合
29. 階層構造がいいのか？ では、データはすべて階層的にするべきだろうか？ 上の例の場合、単に複数項目をまとめたいためだけに 階層構造にしている為、コードを処理する上でも見た 目的にもあまり違いが無い。 そのため、フラットに表した方が良いと言える。 29 階層的に表す場合 フラットに表す場合
30. 階層的 or フラット？ 結論 結論としては、 なるべくフラットにすべきだが、階層化した 方が絶対に良い場合は階層化もあり というのが正しいルールと言える。（Googleスタイル ガイドにも書かれている。） 30
31. エラーの表現 エラーの際は、 ステータスコード + エラー詳細 をクライアントに返す。 31 HTTPのレスポンスの先頭行に付けられる 例) HTTP/1.1 200 OK Server: api.example.com ステータスコード • 適切なステータスコード を使用する。 • エラー詳細はステータス コードでは表現しきれな い詳細なエラー内容を含 める。 エラー詳細
32. 32 美しいWebAPIの作り方 その他・まとめ もう少しで終わり
33. WebAPIを公開する際にできること • APIドキュメントの提供 公開したAPIを多くの人に利用してもらえるようになる第一歩。 API Blueprint(http://apiblueprint.org/)という便利なツールも 存在する。 • サンドボックスAPIの提供 本当のAPIとは別に用意されたテスト環境のこと。ユーザが自 由にAPIを試すことができる。 • APIコンソールの提供 APIコンソールを提供することにより、API利用者はわざわざス クリプトなどを書かなくてもAPIを簡単に試すことができる。 Apigee(https://apigee.com)というAPIコンソールを生成する サービスも存在する。 33
34. WebAPIチェックリスト 本書には、 WebAPIチェッ クリストが付録 している。 WebAPI開発時 に役立てること ができる。 34 (一部抜粋)
35. その他大事なこと • 認証にはOAuth 2.0を使う。 • 個人情報など特定のユーザ以外に漏洩したくな い情報がある場合はHTTPSを使う。 • APIのバージョンの更新は最小限にとどめ後方 互換性に注意する。 • APIのバージョンはメジャーバージョンをURI に含める。 • 実際はもっとたくさんある。 35
36. まとめ WebAPIを公開するとサービスの価値が向上する 36 • 標準仕様、またはデファクトスタンダードに 従う。 • 使いやすい、変更しやすい、頑強である、恥 ずかしくないWebAPIを作る。 WebAPIを美しく設計する そのためには
37. KatLab 夏休みの宿題 平成30年9月14日(金) 平木場 風太 紹介 Web API T h e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~
38. 38 美しいWebAPIの作り方 美しいAPIを 公開するメリット APIって何がいいの？