Web API: The Good Partsの読書感想文
Web API: The Good Partsを読んだので概要と感想を書きます
読んだのは下のリンクの本です
概要
全６章から構成されています
１章 Web APIとは何か
「Web API」というと定義が曖昧だが、この本で言うところのWeb APIとは
「HTTPプロトコルを利用してネットワーク越しに呼び出すAPI」のこと
APIを公開することは自分たちが作ったシステム、集めたデータを無料で公開することなので短期的に見れば損をするようにも見えるが、新しいシステムやサービスを開発する力を持った開発者にAPIを公開することで彼らがサービスに付加価値を与えてくれ、自分たちがコアサービスに注力するための力をもらう事ができる
Web APIを公開していないのであればいますぐに公開したほうが良い
Web APIを設計するときには、美しく設計する事が重要
理由を以下の通り
設計の美しいWeb APIは使いやすい
- APIを使用するのは他者であるため、多くの開発者に簡単に使用してもらうために使いやすく設計する必要がある
設計の美しいWeb APIは変更しやすい
設計の美しいWeb APIは頑強である
設計の美しいWeb APIは恥ずかしくない
世の中に公開されているAPIはよく「REST API」と呼ばれる
一般には「HTTPでアクセスでき、データをXMLやJSONで返すAPI」といった意味合いで使われていますが、RESTとはそもそもRoy Fielding氏が論文で使用した言葉で、その定義通りに実装していくと必ずしも美しい設計にならない場合がある (ex. RESTではURIはリソースを表すため動詞がURIに含まれることを良しないが、serchといった単語をAPIのURIに含めたほうがわかりやすい場合がある)
RESTという言葉にあまりこだわり過ぎないことも大切
２章 エンドポイントの設計とリクエストの形式
APIを使用するために、別サービスがアクセスするURIのことをエンドポイントと呼ぶ
エンドポイントは覚えやすく、どんな機能をもつURIなのかひと目でわかる事が重要なので、URIには適切な英単語を使用し、単数形や複数形にも気をつけたほうが良い
英単語の選択に悩むときは、すでに公開されているサービスのAPIを参考にすると良い
Programmable Webというサービスでは公開されているAPIを検索する事ができる
また、リソースを取得する場合はGET、リソースを新規作成するときはPOSTなどHTTPのメソッドを適切に利用する必要がある
GETメソッドでリソースの作成や削除を行ったりするのは美しい設計とは言えない
ログイン、認証に関してはOAuthを使用する事が多い
OAuthとは認可のための機能で、GoogleやTwitterなどのソーシャルサービスの情報を、自分たちのサービスが利用するための許可を得る事ができる仕組みです
３章 レスポンスデータの設計
APIを設計する際、レスポンスデータをどのように設計するかを考える必要がある
基本的にはJSON or XMLという選択になるが世の中のAPIを見るとJSONがデファクトスタンダードとなっている
データ内部にstatusコードなどを含むAPIもあるがWeb APIはHTTPを使用しており、HTTPにはヘッダの概念があるためメタデータなどはレスポンスボディに含めず、HTTPのヘッダを使用したほうが良い
レスポンスは出来るだけフラットな構造 (階層構造ではない)のほうが良いが、必ずしもフラットにする必要はない
Googleのスタイルガイドでも、なるべくフラットにすべきだけど階層化したほうが良い場合もあるといったニュアンスになっている
JSONでレスポンスを返す場合は「key: value」の形でデータを返す
この時のkeyの名前はURIの時と同様に、各データの名前が簡潔で理解しやすく、適切な単数複数が用いられていると良い
最後にエラーの表現では、適切なステータスコードで表現する必要がある
ステータスコード200を返して、ボディにエラーメッセージを書くなどは基本的にNG
また、エラーの形式を統一し、クライアント側で機械的にエラーの詳細を理解可能にするのが良い
４章 HTTPの仕様を最大限利用する
Web APIはHTTTP上で通信を行うので、HTTPの仕様を理解してそれを活用したほうが使い勝手が良いものとなる
ステータスコード、メディアタイプ (Content-Type)は適切に使用し、一般的なものを返す
クライアントが適切なキャッシュを行えるように、Cache-Controlヘッダなどを使用し、適切な情報を返す必要がある
５章 設計変更しやすいWeb APIを作る
Web APIはサービスの変更に応じて変更を加えていかなければならない
ただAPIを変更すると、APIを使用している別サービスに影響が出る可能性があるので注意が必要である
APIをバージョン管理し、古い形式と新しい形式どちらもサポートする方法が良い
また、後方互換性がない変更を加えるときはメジャーバージョンを増やし、APIのURIにメジャーバージョンを加えると今利用しているAPIのバージョンがわかりやすくなる
同時に複数のバージョンをメンテナンスするのは手間がかかるため、古いバージョンのAPIはいずれ廃止するほうが良いが、すぐに提供を終了するとこれも現在利用しているユーザーに影響があるため、少なくとも６ヶ月程度は公開を続けておく必要がある
６章 堅牢なWeb APIを作る
Web APIは通常のウェブアプリケーションと同様の安全性やセキュリティと、その他にAPIならではの対策も必要となる
通常のウェブアプリケーションと同様に個人情報など特定のユーザー以外に漏洩したくない情報がある場合はHTTPSを使う。またXSS、XSRFなどを防ぐためContent-TypeやHTTPメソッドを適切に使用する必要がる
JSONハイジャックとはscript要素を使ってユーザー情報をAPIから取得し、それを別サーバーに送る事でユーザー情報を盗み出す攻撃方法
JSONハイジャックもContent-Typeを正しく利用する、X-Requested-Withヘッダを使用しJSONをscript要素で読み込めなくする、JSONをJavaScriptとして読み込めなくするなどして対策をする事ができる
また大量にアクセスを行う事でサーバーの負荷を増大させるDoS攻撃に対しては、単位時間当たりに許可されるアクセス数を制限するレートリミットを設定しておく事が有効である
感想
Web APIを公開する意義から始まり、どのように設計していくと使いやすいAPIとなるのか、設計の際に気を付けるポイントは何なのかが具体的に書いてあってわかりやすかった
具体例としてTwitterやFacebookなどが実際に公開しているAPIを示していたのもイメージが湧きやすくよかった
WebサービスとWeb APIがどう違うのか、設計やセキュリティ面で気をつけることの違いなど、これからAPIを設計していこうという時に読むと必要な知識が網羅的に得られて良さそう
ページ数も200P程度と短くまとまっていて2時間くらいで読める
