【技術書まとめ 2 】Web API: The Good Parts

本書の紹介

Web API the Good Parts - O'Reilly Japan

TL;DR

設計の美しい API は、使いやすい、変更しやすい、頑強である、恥ずかしくない

本書を読むことで、 どうやって API を設計し運用すれば効果的なのか 、 ありがちな罠やアンチパターン を避けるためにはどういう点に気をつけなければいけないのか など Web API 設計の考え方と手法を学ぶことができます。

僕のモチベーション

• Bison ( Salesforce ラッパー ) の開発への足掛かりとなる知識のインプット
• 知の探求 - ビジョン・イズムの体現
• 【技術書まとめ】 をシリーズ化していこうという 挑戦 冒険

各章のメモ

1 章 Web API とは何か

• Web API の重要性
  • IaaS, BaaS, DaaS など API の利用を前提とした サービスの登場。
  • API を用意することで様々なサービスとの共存共栄をはかることができる。
  • API エコノミー
    • API そのものの構築や管理をビジネスにしたサービスの誕生。
    • 世界の潮流 サービスが公開したら API を当然公開するよね （日本もこれに向かうのか）
• どうして API を公開するのか
  • サービスを公開していて、 API を公開していないならすぐにすべき！
  • （簡潔に言えば） そのサービスでできること全てを API 経由で行える ようにする
  • Web API を公開することで得られるもの
    • サービス利用範囲・価値提供範囲の拡大、サービス同士の連携
    • 今、起こりつつあるAPIエコノミーとか何か？ | TechCrunch JAPAN
• Web API を美しく設計する重要性
  • 冒頭にもあるけどこの一言に尽きる😤 「 設計の美しい API は、使いやすい、変更しやすい、頑強である、恥ずかしくない 」
• Web API を美しくする原則
  • 仕様が決まっているものに関しては仕様に従う
  • 仕様が存在しないものに関してはデファクトスタンダードに従う
• REST という言葉にこだわりすぎない

  • REST を厳密に考えていくと、深い議論になりそうなので基本的には触れません。REST という言葉を使うことで混乱を招くことは避けるようにします。

    • ref. Representational State Transfer | wikipedia
    • ref. REST APIs must be hypertext-driven
• 対象となる開発者の数と API の設計思想
  • LSUDs ( large set of unknown developers ) と SSKDs ( small set of known developers ) という概念が存在する
    • ref. The future of API design: The orchestration layer
  • LSUDs : API をドキュメントとともに公開して、誰もが使えるような場合。
    • さまざまなユースケースを想定してなるべく広く汎用的にしなければいけない。
  • SSKDs : API を利用する開発者が限定されている場合。
    • 特定の開発者やその先に存在するエンドユーザにとって便利で使いやすくあるべき。

2 章 エンドポイントの設計とリクエストの形式

• API として公開する機能を設計する
  • エンドポイントの基本的な設計
    • 覚えやすく、どんな機能を持つ URI なのかが一目でわかる
  • HTTP メソッドとエンドポイントを正しく対応させて使用する
  • API のエンドポイント設計
    • 複数形の単語を使用する
    • 利用する単語に気を付ける
    • スペースやエンコードを必要する文字を使わない
    • 単語をつなげる必要がある場合はハイフンを利用する
  • 検索とクエリパラメータ
    • pert_page/page や limit/offset などの組み合わせで取得数と取得位置のクエリパラメータを渡す。
      • http://api.example.com/users?per_page=50&page=3
    • 検索の場合は、キーで絞り込みの要素、値には絞り込む値を指定する。
      • http://api.example.com/people-search?name=yoshimitsu&age=24
    • 一意なリソースを表すのに必要な情報かどうか、 省略可能かどうか でクエリパラメータとパスのどちらに含めるのが正しいのか使い分ける。
• 認証には OAuth 2.0 を使う
  • OAuth ：あるサービスのデータを第三者がアクセスした場合に利用する仕組み
• ホスト名とエンドポイントの共通部分
  • example.com というドメイン でサービスが提供されている API のホスト名は api.example.com が一番わかりやすいし、アクセスを DNS レベルで分割できるので管理も楽。
• 「1 スクリーン 1 API コール、1 セーブ 1 API コール」
• HATEOAS( hypermedia as the engine of application state ) ：返すデータの中に、次に行う行動、取得するデータ等のURI をリンクとして含める
  • まだ概念として世に広まっているとは言えない。
  • オープンに公開する LSUDs 向け API には向かない。

3 章 レスポンスデータの設計

• データフォーマットはデファクトスタンダードな JSON に対応しておけば問題ない
• データの内部構造の考え方
  • クエリパラメータを用いてレスポンスの内容をユーザが選択できるようにする
  • レスポンスデータはエンベロープでくるむのは冗長で望ましくないし、できるだけフラットにすべき
    • ref. JSON Style Guide | Google
  • 配列のデータを返したい時もオブジェクトで包んで返した方が良い
    • オブジェクトにキーをつけてあげることで何を示しているのか明確にできる。
    • レスポンスデータをオブジェクトに統一することができる。
    • セキュリティ上のリスクを避けることができる。
  • 一連のデータで高施されるデータセットを取得したい場合は、データに続きがあるかを hasNext という名前で情報を返すようにする。あるいは、 Google+ のように、次のページアクセスするためのパラメータを返す。
• 各データのフォーマット
  • データの名前
    • 多くの API で同じ意味に利用されている一般的な単語を用いる
    • なるべく少ない単語数で表現する
    • 複数の単語を連結する場合、その連結方法は API 全体を通して統一する
    • 変な省略形は極力利用しない
    • 単数形／複数形に気を付ける
  • 性別データはキーを gender 、型を文字列にする
    • sex ( integer ) 「 0: 不明、1: 男性、2: 女性」
    • gender ( string ) 「 "male" 、 "female"」
  • 日付のフォーマット
    • 基本的に RFC3339 を利用すべき 2019-11-06T11:30:22+09:00
• エラーの表現
  • 正しいステータスコードを返す。
  • レスポンスボディにエラーの詳細情報を格納して返す
  • メンテナンス中の場合は、ステータスコード 503 と HTTP ヘッダ Retry-After （次にいつアクセスできるようになるか）を返すのがユーザに対して親切だし SEO 的にも推奨されている。
  • 他人にブロックされているのを知らせたくない時など意図的に不正確な情報を返す場合もある。（ 403 だとブロックと伝わるけど、 404 だとそもそも存在しないと同義）

4 章 HTTP の仕様を最大限利用する

• HTTP の仕様を利用する意義
  • Web API は HTTP 上で通信を行うので、 HTTP の仕様をしっかりと理解して、活用した方がより使い勝手が良いため
• 何度も言うが… 適切なステータスコードを用いる
  • ref. HTTP レスポンスステータスコード | MDN web docs
• Content-Type ヘッダを使って適切な、なるべく一般的なメディアタイプを指定する
• クライアントが適切にキャッシュを行えるように情報を返す
  • Expiration Model （期限切れモデル）：あらかじめレスポンスデータに保存期限を決めておき、期限が切れたら再度アクセスをして取得を行う。
  • Validation Model （検証モデル）：今保持しているキャッシュが最新であるかを問い合わせて、データが更新されていた場合にのみ取得を行う。

5 章 設計変更しやすい Web API を作る

• API のバージョン更新は最小限にとどめて、後方互換性にも注意する
  • バージョニングのルールは セマンティックバージョニング に則る
    • パッチバージョン ：API に変更がないバグ修正
    • マイナーバージョン ：後方互換性のある機能変更や特定の機能が廃止される場合
    • メジャーバージョン ：後方互換性のない変更
• API のバージョンはメジャーバージョンを URI に含める
  • ex ) https://api.example.com/v1/statuses
• API の提供終了時はすぐに終了するのではなく 最低 6 ヶ月 公開を続ける
  • twitter API の継続的な告知や Blackout Test は大変参考になる。

6 章 堅牢な Web API を作る

• 個人情報など特定のユーザ以外に漏洩したくない情報がある場合は HTTPS を使う。
  • 100% 安全とは言えないが、対応が簡単かつカジュアルに情報を盗み見られることは少なくなる。
• 通常のウェブと同様のセキュリティだけでなく JSON ハイジャックなど API 特有の脆弱性に気を配る。
  • XSS ：動的にHTMLを生成する際に、エスケープせずに出力しているため、生成される HTML に攻撃者の作成した HTML や JavaScript が埋め込まれてしまう脆弱性
  • XSRF ：サイトを跨いで偽造したリクエスト送りつけることにより、ユーザが意図していない処理をサーバに実行させてしまう脆弱性
  • JSON ハイジャック ：API から JSON で送られてくる情報を悪意のある第三者から盗み取られる脆弱性
• セキュリティ強化に繋がる HTTP ヘッダをきちんと付ける。
  • X-Content-Type-Options , X-XSS-Protection , X-Frame-Options , Cotent-Security-Policy , etc ... ʕ◔ϖ◔ʔ(多いな
• レートリミットを設けることで一部のユーザによる過度のアクセスによる負荷を防ぐ。
  • くどいようだけどステータスコード "429 Too Many Requests"
  • レートリミットはドキュメントに書いてあげる + API 利用者向けのダッシュボードとかに書いてあげるようが親切
  • レートリミットを超えるユーザは優良な顧客なので適切に設定しよう、あるいは「制限を超えるアクセスが必要な場合は連絡してね」というアクセス制限の緩和も検討の余地あり。

まとめ

API を開発していく上では必要な設計や考え方、手法について学べました。（既に理解されているとは思いますが）今後 Web API の開発に携わる方は是非ご一読をお勧めします。

おまけ

最後まで読んでいただきありがとうございます。
意見や指摘等あればコメントいただけると大変嬉しいです。

このシリーズを続けていけたらと思ってます。いいね 👍 やコメントいただけると大変励みになりますのでお願いします。