読者です 読者をやめる 読者になる 読者になる

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

book

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

1章 Web APIとは何か

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

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

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

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

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

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

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

  • JSONJavaScript として読み込んだときに構文エラーになるから JSON インジェクション防止になる
  • ページングする場合に次のページがあるかどうかといった情報も含めることができる

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

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

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

  • 成功したら 200 番台
  • クライアントが原因のエラーなら 400 番台
  • サーバー側が原因のエラーなら 500 番台

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

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

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

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

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

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

6章 堅牢なWeb APIを作る

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