【書籍まとめ＆レビュー】Web API: The Good Parts

はじめに

レビュー

この本を読もうと思ったきっかけは実務でAPIの要件定義、設計をすることになったためです。
読んだ感想としては一言でいうと、分かりやすくとても勉強になり読んで良かったと思っています。
五段階で星５ですね！

基本的なAPI設計における考え方や歴史から始まり、エンドポイント設計、リクエスト形式、レスポンスデータ設計等一通りAPI設計に必要な知識を身に付けることができました。
個人的にOAuthなど認証周りについても、詳しく書かれていることが嬉しかったです。

WebAPIの書籍で検索をすると一番上に表示されるくらい有名で王道な書籍です。
「APIについて勉強をしてみたい方」、「実務で必要になった方」是非、読んでみてください！

以降では、各章の概要を記載しています！

第１章 WebAPIとは何か

• WebAPIとは
  HTTPプロトコルを利用してネットワーク越しに呼び出すAPI
  ※APIとは・・・Application Programming Interfaceの略。ソフトウェアコンポーネントの外部インターフェース、つまり機能はわかっているけれどもその中身の実際の動作は詳しくわからない（知らなくてもよい）機能のカタマリを外部から呼び出すための仕様のこと。

• Web APIはリンクをブラウザなどでクリックしたりしてアクセスするものではなく、データをプログラムが取得して、他の目的に使うもの。（そのためレスポンスはJSON（XML）が主流。）

• APIの設計では、公開するものを決め、アクセス先のエンドポイントを決め、適切なリクエスト、レスポンス形式、セキュリティやアクセス制限について考えていく必要がある。

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

• 提供する機能を決める
  公開したAPIがどのように使われるのか、そのユースケースをきちんと考えることが重要。

• エンドポイントとは
  APIにアクセスするためのURIのことを言う。APIは通常さまざまな機能がセットになっているため複数のエンドポイントを持つ。

• エンドポイント設計
  覚えやすくどんな機能を持つURIなのか一目でわかることが重要。
  →短く入力しやすいURI
  →人間が読んで理解できるURI
  →大文字小文字が混在していないURI（小文字統一が良い）
  →改造しやすい（Hackableな）URI
  →サーバー側のアーキテクチャが反映されていないURI（セキュリティ面）
  →ルールが統一されたURI

• エンドポイント設計の注意点
  →複数系の名詞を利用する。
  →利用する単語に気を付ける。(find or searchなど)
  →スペースやエンコードを必要とする文字を使わない。
  →単語をつなげる必要がある場合はハイフン（-）を利用する。

• クエリパラメータとパスの使い分けの判断基準
  →一意なリソースを表すのに必要な情報かどうか（URIがリソースを表すものという思想からきている。ユーザーIDなどはユーザーIDを指定することで参照したい情報が一意に決まるためパスに入れた方が良い。）一方でアクセストークンなどは利用者の認証が目的であり、リソースとは無関係のためパラメータが適している。
  →省略可能かどうか（iffset、limitなど）

• ログインとOAuth
  ログイン周りのAPIを考える際に真っ先に検討するべきなのがOAuth。広く第三者に公開されるAPIにおいて認可（authorization）を行うために用いられる。

第３章 レスポンスデータの設計

• データフォーマットについて
  基本的にはJSONを使用することにし、需要や必要があればXMLに対応する。
  (理由としては、JSONのほうがシンプルで同じデータを表すのにもサイズが小さくて済むこと、クライアントのデフォルト言語のJavaScriptと相性が良いこと。)

• データ構造の考え方
  →できる限り少ないアクセス回数ですむAPI設計を心かけるべき。
  →レスポンスの内容をユーザーが選べるようにする。（クエリパラメータを使ってユーザー情報のうち、名前と年齢を指定する等）
  →HTTPがエンベロープの役割を果たしているため、エンベロープは基本的に不要。
  →構造はできる限り、フラットな方が良い。階層化した方がわかりやすい場合もある。

• 各データのフォーマット
  →多くのAPIで同じ意味に利用されている一般的な単語を用いる
  →なるべく少ない単語数で表現する
  →単語の連結方法はAPIを通して統一する
  →性別などのデータを数値で返すか、文字列で返すかはサービスの性質による。
  →日付データはRFC3339（2022-10-01T11:30:22+09:00）を使う。

• エラーの表現
  →適切なステータスコードを使うことが重要。また、エラーが発生した際にはエラーの詳細をクライアントに返す。
  →エラーメッセージはボディに格納する。
  →サーバーエラー時等にHTMLが返ることを防ぐ。

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

• Web APIではHTTPヘッダにさまざまな情報を入れることができるため、わざわざレスポンスデータをエンベロープで包まなくて良い。

• ステータスコードを正しく使う
  →100番台（情報）、200番台（成功）、300番台（リダイレクト）、400番台（クライアントサイドに起因するエラー）、500番台（サーバーサイドに起因するエラー）

• キャッシュについて
  →キャッシュの仕様を理解し、有効活用することでサーバー負荷を減らす。
  →キャッシュの適切な期限はサービスの性質により変わる。更新頻度が高いサービスの場合、期限を短くする。

• メディアタイプの指定
  →メディアタイプ・・・データ形式のこと。レスポンスがJSONなのか、画像、それともテキストファイルなのかetc
  →Content-Typeヘッダを使ってメディアタイプを指定することが非常に重要。（クライアントの多くはContent-Typeの値でデータ形式を判断している。）

• クロスオリジンリソース共有
  →異なる生成元ドメインからのアクセスに対して、特定の生成元からのみアクセスを許可することができる。JSONPよりもセキュアである。クライアントからOriginというリクエストヘッダを送る必要がある。このヘッダにはアクセス元となる生成元を指定する。

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

• APIのバージョンの更新は最低限にとどめ、後方互換性にも注意する。

• 新しい機能は別のバージョン（エンドポイント）として公開する。つまり、複数のバージョンのAPIを公開する。

• APIのバージョンはメジャーバージョンをURIに含める。

• APIの提供終了時はすぐに終了するのでなく最低6ヶ月公開を続ける。

第６章 堅牢なWeb APIを作る

• 個人情報など特定のユーザー以外に漏洩したくない情報がある場合はHTTPSを使用する。

• XSS、XSRFなど通常のウェブと同様のセキュリティだけでなく、JSONハイジャックなどAPI特有の脆弱性にも気を配る。

• レートリミットを設けることで一部のユーザーによる過度のアクセスによる負荷を防ぐ。

終わりに

本記事はここまでとなります。
ご覧いただきありがとうございました。ご指摘等がございましたら頂けますと嬉しいです。
引き続き、プログラミングについて定期的に発信していきますのでよろしくお願いします！
また、もしよろしければtwitterもフォローしていただけると嬉しいです！🐢