美しいWebAPIの作り方.pdf

Slide 1

Slide 1 text

KatLab 片山徹郎研究室平成30年9月14日(金) 平木場風太紹介 Web API T h e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~

Slide 2

Slide 2 text

背景1 2 家計簿サービスを作ったぞ！いろんな人に使ってもらいたいな〜

Slide 3

Slide 3 text

背景2 3 そうだ！ WebAPIを作ってプログラマ達の力を借りよう！！プログラマ軍団

Slide 4

Slide 4 text

背景3 4 でもWebAPIの設計ってどうやんの？ HTTPもサーバもわかるけど… うおっ

Slide 5

Slide 5 text

アジェンダ 1. 背景 2. WebAPIとは 3. 紹介する本の概要 4. 美しいWebAPIを作るには 5

Slide 6

Slide 6 text

6 美しいWebAPIの作り方 WebAPIの概要まずはWebAPIをおさらいしよう！

Slide 7

Slide 7 text

WebAPIとは • HTTPプロトコルを利用してネットワーク越しに呼び出すAPI(Application Programming Interface)のこと • あるURIにアクセスすることで、サーバ側の情報を書き換えたり、サーバ側に置かれた情報を取得できたりすることができるWebシステム。 • プログラムからサービスに容易にアクセスできる。 7

Slide 8

Slide 8 text

実際にWebAPIを利用してみる利用API：鯖江市コミュニティバス（つつじバス） ⚫ 福井県鯖江市で運行しているバス。 ⚫ 時刻表、バス停、走行中バスの座標や、運行情報等をWebAPIとして提供している。 ⚫ http://www.city.sabae.fukui.jp/users/tutujibus/web-api/web-api.html 8

Slide 9

Slide 9 text

“運行状況に関するお知らせ” を確認する ← APIの使い方。エンドポイント、リクエストパラメータ、レスポンスを確認しておく。 ↓ ブラウザで利用。 (全てのAPIがブラウザで利用できるわけではない) 9

Slide 10

Slide 10 text

10 美しいWebAPIの作り方 Web API The Good Parts の概要この本は何？？

Slide 11

Slide 11 text

紹介する本 Web API: The Good Parts • 著者: 水野貴明 • 発行月: 2014年11月 • ISBN: 978-4-87311-686-0 • 出版社: オライリージャパン Web APIの設計、開発、運用についての解説書。 XML over HTTP方式、JSON over HTTP方式を扱う。 11

Slide 12

Slide 12 text

各章の概要1 1章 Web APIとは何か → WebAPIを取り巻く現状と本書の内容の活かし方など。 2章エンドポイントの設計とリクエストの形式 →クライアントからサーバに対して行うアクセスの設計など。 3章レスポンスデータの設計 →リクエストに対して返されるレスポンスデータの構造の設計など。 12

Slide 13

Slide 13 text

各章の概要2 4章 HTTPの仕様を最大限利用する(省略) → HTTPの仕様をどのようにAPIに反映させるべきか。 5章設計変更をしやすいWeb APIを作る(省略) → 公開したAPIを安全に修正する方法。 6章堅牢なWebAPIを作る(省略) → 想定しないアクセスによる影響を最小限に抑えるためのセキュリティや安定性。 13

Slide 14

Slide 14 text

各章の概要3 付録A WebAPIを公開する際にできること → WebAPIにおいて、考慮すべき設計以外の事柄の紹介。付録B WebAPIチェックリスト → 本書で触れた内容をきちんと設計に反映できているかを簡単にチェックするための一覧表。 14

Slide 15

Slide 15 text

APIを公開するということ APIを公開することでさまざまな付加価値を他の企業や個人が提供してくれる。サービスの価値や情報の質が向上する可能性がある！ 15 したがって

Slide 16

Slide 16 text

例えば家計簿サービスを公開する 16 開発者ユーザ家計簿サービス WebAPI サードパーティ開発者家計簿アプリ家計簿ブラウザ拡張機能サービス価値の向上

Slide 17

Slide 17 text

WebAPIを美しく設計しようしかし、先の例は美しいWebAPIである場合！ 17 美しくないWebAPI 美しいWebAPI したがって、 WebAPIを美しく設計することが大事

Slide 18

Slide 18 text

設計の美しいWebAPIとは？美しいAPI設計の“美しい”とは • よく考えられている • わかりやすく整理されている • 無駄がないなどの完成度の高さ 18 設計の“美しい”WebAPIは • 使いやすい - サードパーティ開発者の負担軽減 • 変更しやすい - 利用者に影響ない変更が可能 • 頑強である - 不正利用の防止、ダウンタイム低減 • 恥ずかしくない - サービス開発者の技術レベルを誇示

Slide 19

Slide 19 text

美しいWebAPIを作る際の重要な原則本書の思想の根幹をなす重要な原則 • 標準仕様が決まっているものに関しては仕様に従う • 標準仕様が存在していないものに関してはデファクトスタンダードに従うすでにあるルールに従うことで、開発したAPIを利用者が容易に利用できたり、既存のクライアントライブラリの流用が可能になったりする。 → エコシステムの拡大 19

Slide 20

Slide 20 text

20 美しいWebAPIの作り方エンドポイントの設計入口はわかりやすい方が良い！！

Slide 21

Slide 21 text

重要な原則 APIにアクセスするためのURI 例) ToDoリストでユーザ情報を取得するAPIのエンドポイント → https://api.example.com/v1/users/me 21 原則覚えやすく、どんな機能を持つURIなのかがひと目でわかるエンドポイント

Slide 22

Slide 22 text

守るべき項目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

Slide 23

Slide 23 text

守るべき項目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

Slide 24

Slide 24 text

HTTPメソッドに合わせた処理をする1 24 HTTPでのアクセス時に指定する命令。例) GET /v1/users/123 HTTP/1.1 Host: api.example.com HTTPメソッド

Slide 25

Slide 25 text

HTTPメソッドに合わせた処理をする2 それぞれの目的に応じて適切にメソッドを使い分ける 25

Slide 26

Slide 26 text

26 美しいWebAPIの作り方レスポンスデータの設計プログラムに優しい手紙を書こう！

Slide 27

Slide 27 text

データフォーマットレスポンスデータでどういったデータフォーマット（構造化データの表現方法）を採用するかを決める。 27 JSONをデフォルトとして対応し、必要があればXMLにも対応する！ JavaScript Object Notationの略。ポピュラー。 JSON Extensible Markup Languageの略。昔はポピュラー。 XML

Slide 28

Slide 28 text

階層的 or フラット？同じデータでも、フラットに表すことも階層的に表すこともできる。どちらにすべきだろうか？上の例の場合、senderとreceiverのようにどちらも同じユーザという構造を表しているので、階層構造で表現した方が良いと言える。 28 階層的に表す場合フラットに表す場合

Slide 29

Slide 29 text

階層構造がいいのか？では、データはすべて階層的にするべきだろうか？上の例の場合、単に複数項目をまとめたいためだけに階層構造にしている為、コードを処理する上でも見た目的にもあまり違いが無い。そのため、フラットに表した方が良いと言える。 29 階層的に表す場合フラットに表す場合

Slide 30

Slide 30 text

階層的 or フラット？結論結論としては、なるべくフラットにすべきだが、階層化した方が絶対に良い場合は階層化もありというのが正しいルールと言える。（Googleスタイルガイドにも書かれている。） 30

Slide 31

Slide 31 text

エラーの表現エラーの際は、ステータスコード + エラー詳細をクライアントに返す。 31 HTTPのレスポンスの先頭行に付けられる例) HTTP/1.1 200 OK Server: api.example.com ステータスコード • 適切なステータスコードを使用する。 • エラー詳細はステータスコードでは表現しきれない詳細なエラー内容を含める。エラー詳細

Slide 32

Slide 32 text

32 美しいWebAPIの作り方その他・まとめもう少しで終わり

Slide 33

Slide 33 text

WebAPIを公開する際にできること • APIドキュメントの提供公開したAPIを多くの人に利用してもらえるようになる第一歩。 API Blueprint(http://apiblueprint.org/)という便利なツールも存在する。 • サンドボックスAPIの提供本当のAPIとは別に用意されたテスト環境のこと。ユーザが自由にAPIを試すことができる。 • APIコンソールの提供 APIコンソールを提供することにより、API利用者はわざわざスクリプトなどを書かなくてもAPIを簡単に試すことができる。 Apigee(https://apigee.com)というAPIコンソールを生成するサービスも存在する。 33

Slide 34

Slide 34 text

WebAPIチェックリスト本書には、 WebAPIチェックリストが付録している。 WebAPI開発時に役立てることができる。 34 (一部抜粋)

Slide 35

Slide 35 text

その他大事なこと • 認証にはOAuth 2.0を使う。 • 個人情報など特定のユーザ以外に漏洩したくない情報がある場合はHTTPSを使う。 • APIのバージョンの更新は最小限にとどめ後方互換性に注意する。 • APIのバージョンはメジャーバージョンをURI に含める。 • 実際はもっとたくさんある。 35

Slide 36

Slide 36 text

まとめ WebAPIを公開するとサービスの価値が向上する 36 • 標準仕様、またはデファクトスタンダードに従う。 • 使いやすい、変更しやすい、頑強である、恥ずかしくないWebAPIを作る。 WebAPIを美しく設計するそのためには

Slide 37

Slide 37 text

KatLab 夏休みの宿題平成30年9月14日(金) 平木場風太紹介 Web API T h e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~

Slide 38

Slide 38 text

38 美しいWebAPIの作り方美しいAPIを公開するメリット APIって何がいいの？