『Web API : The Good Parts』を読んだ

Single Page Application を作る場合、Web API も作ることになるので、勉強のために購入して読んでみた。以下、感想と読書メモ。

Web API は JSON over HTTP とも言える。REST API とは呼ばない。

Web API を提供する対象として、未知のたくさんの開発者(LSUDs)と既知の小数の開発者(SSKDs)がある。大半のアプリは SSKDs が対象になるだろうな。今作っている Web API もそう。

Web API のエンドポイントの設計は REST と同じ。ただ、単語をつなげるときアンダースコアを使っていた。ホスト名と揃えるならハイフンの方が確かに良いかもしれない。

レスポンスデータは JSON で返すとして、API で配列を返したいときに配列のまま返すか、オブジェクトでラップするかは悩む。

オブジェクトでラップすれば

というメリットはあるけど…。自分の中ではまだ結論が出ていない。

Web API が返すレスポンスのステータスコードは

という風に HTTP の仕様にきちんと従う。全部 200 を返してレスポンスボディにエラーコードを入れる、なんて行儀悪いことはしてはいけない。

独自の HTTP ヘッダーは定義することがあるかもしれないが、独自のメディアタイプの定義はやりすぎだな。 HTTP クライアントが対応していない可能性高いし。

API バージョンはパスに入れる派だな。パスに入れておけば使う側は必ずバージョンを指定することになるわけだから。

あと、API のバージョン管理はセマンティックバージョニングで。

オーケストレーション層は BFF (Backend For Frontend) と同じかな。汎用的な Web API と、それをクライアントが使いやすい形に束ねて加工した Web API を提供する。 Web とモバイルみたいに、クライアントが増えてきたらやることになりそう。

Web API も Web サービスなので、セキュリティは当然気をつけている。 XSS や CSRF はフレームワークがサポートしてくれるが、パラメーターの改ざんだったり、大量アクセスへの対策は自前で作りこむ必要がありそうだ。