Skip to content

「Web API: the Good Parts」を読んで

  • 読書
  • API
  • Web

📅 2020-07-25

⏱️ 12 min read

本書の紹介

key value
タイトル Web API: The Good Parts | 水野 貴明 |本 | 通販 | Amazon
著者名 B水野 貴明 (著)
出版社名 オライリージャパン
読了日 2019/11/08

各章の要約

1 章 Web API とは何か

  • Web API の重要性

    • IaaS, BaaS, DaaS など API の利用を前提とした サービスの登場。
    • API を用意することで様々なサービスとの共存共栄をはかることができる。
    • API エコノミーの拡大。 1

  • なぜ API を公開するのか？

    • サービス利用範囲・価値提供範囲の拡大
    • サービス同士の連携

  • Web API を美しく設計する重要性

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

  • Web API を美しくする原則

    • 仕様が決まっているものに関しては仕様に従う
    • 仕様が存在しないものに関してはデファクトスタンダードに従う
  • REST という言葉にこだわりすぎない 2 3

  • 対象となる開発者の数と API の設計思想

    • LSUDs ( large set of unknown developers ) と SSKDs ( small set of known developers ) という概念が存在する。4

    • LSUDs : API をドキュメントとともに公開して、誰もが使えるような場合。

      • さまざまなユースケースを想定してなるべく広く汎用的にしなければいけない。

    • SSKDs : API を利用する開発者が限定されている場合。

      • 特定の開発者やその先に存在するエンドユーザにとって便利で使いやすくあるべき。

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

  • API として公開する機能を設計する

    • エンドポイントは基本的に 覚えやすく、どんな機能を持つ URI なのかが一目でわかる ように設計する。
    • HTTP メソッドとエンドポイントを正しく対応させて使用する。

    • API のエンドポイント設計

      • 複数形の単語を使用する。
      • 利用する単語に気を付ける。
      • スペースやエンコードを必要する文字を使わない。
      • 単語をつなげる必要がある場合はハイフンを利用する。

    • 検索とクエリパラメータ

      • per_page/page や limit/offset などの組み合わせで取得数と取得位置のクエリパラメータを渡す。

        • https://api.example.com/users?per_page=50&page=3

      • 検索の場合は、キーで絞り込みの要素、値には絞り込む値を指定する。

        • https://api.example.com/people-search?name=mike&age=24
      • 一意なリソースを表すのに必要な情報かどうか、 省略可能かどうか でクエリパラメータとパスのどちらに含めるのが正しいのか使い分ける。
  • 認証には OAuth 2.0 5 を使う。

  • ホスト名とエンドポイントの共通部分

    • example.com というドメイン でサービスが提供されている API のホスト名は api.example.com が最も分かりやすく、アクセスを DNS レベルで分割できるので管理も楽。
  • 「1 スクリーン 1 API コール、1 セーブ 1 API コール」
  • HATEOAS 6 の概念は、まだ世に広まっているとは言えない。

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

  • データフォーマットはデファクトスタンダードな JSON に対応しておけば問題ない。
  • クエリパラメータを用いてレスポンスの内容をユーザが選択できるようにする。
  • レスポンスデータはエンベロープでくるむのは冗長で望ましくないし、できるだけフラットにすべきである。7

  • 配列のデータを返したい時もオブジェクトで包んで返した方が良い。

    • オブジェクトにキーをつけてあげることで何を示しているのか明確にできる。
    • レスポンスデータをオブジェクトに統一することができる。
    • セキュリティ上のリスクを避けることができる。
  • 一連のデータで構成されるデータセットを取得したい場合は、データに続きがあるかを 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 の仕様をしっかりと理解して、活用した方がより使い勝手が良いため。
  • レスポンスには、適切なステータスコードを用いる。
  • 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 を開発していく上では必要な設計について考え方や手法について学ぶことができた。今後の API 開発へ活かしていけたらなと思う。またそれに携わる方は是非ご一読をお勧めする。

参考にさせていただいたサイト

  1. API そのものの構築や管理をビジネスとするサービスが誕生したり、世界的にも「サービスをローンチしたら API も公開するよね！」という風潮になりつつある。[ref.] 今、起こりつつあるAPIエコノミーとか何か？ | TechCrunch JAPAN

    ↩

  2. 本書では、『REST を厳密に考えていくと、深い議論になりそうなので基本的には触れません。REST という言葉を使うことで混乱を招くことは避けるようにします。』というふうに明言されている。ここで改めて言葉の確認をしたい方はこちらをご参照ください。 [ref.] Representational State Transfer - Wikipedia

    ↩

  3. REST APIs must be hypertext-driven » Untangled

    ↩

  4. The Future of API Design: The Orchestration Layer

    ↩

  5. OAuth とは、あるサービスのデータを第三者がアクセスした場合に利用する仕組み

    ↩

  6. HATEOAS( hypermedia as the engine of application state ) とは、レスポンスとして返すデータの中に、次に行う行動、取得するデータ等のURI をリンクとして含める形式。

    ↩

  7. 下記で述べられている。 [ref.] JSON Style Guide | Google

    ↩
← PrevNext →
  • © ysmtegsr 2019 - 2021