Web API: The Good Partsを読んだ感想と個人的見解

はじめに

新プロジェクトで一から API 設計・開発をやる機会があり、それきっかけで読んでみたかった技術書のうちの一つWeb API: The Good Partsを読みました。感想および個人的見解をまとめていきます。

本技術書は、設計周りだけでなく API を公開することを想定した話が多く納得した点が多くありました。特に、

は一般公開するにあたっては当たり前だけども、普段自分が外部公開をする API を作らないこともあり、勉強になりました。（~~JSON インジェクションに関しては意識できてなかった。。~~）

その他、印象に残ったトピックとしては

設計の際に REST を意識しすぎない

一例をあげるなら、REST でいう URI はリソース（ある実体があつまった集合体; e.g. posts: 投稿という実体があつまった集合体）であり、それに加えて場合に適した HTTP メソッドを指定してエンドポイントを設計するのが主流だと自分は考えていました。

しかし、検索用の API のエンドポイントにsearchという動詞を入れてあげて、より用途をわかりやすくしたり、バージョンを含めたりすることでユーザーにどのバージョンを使うのがを明示的に指定してもらったりというケースは現実的にはありえます。これは厳密にいうと、REST に反したケースです。

つまり、REST の考え方に反していたとしても、それがユーザーにとってのわかりやすさや使いやすさをより向上するものであればそれはよいことだと腑に落ちました。

リクエストもレスポンスもシンプルであれ

必要以上にフィールドをオブジェクトで包むケースは、使う側の実装の負担になったりそもそも冗長な表現である可能性があるため、できるだけシンプルな階層で送ってもらい、返すことが大事だと再認識しました。

ただ、将来的な設計を考えると、レスポンスに関してはなるべく共通化しておくことは大事だなと感じていて、自分ならなるべく階層はフラットに作りたいけど、共通化の面も考えて一個階層を深く作ってあげます。（以下サンプル）

{
  "error": {
    // エラーの中身はエンドポイントやステータスごとに返したいものを入れる
  },
  "data": {
    // 成功した時に中身が入り、エンドポイントごとに返したいものを入れる
  }
}

ですので一番大事なのは、

どういう API を作りたいかというところに立ち返って、リクエスト・レスポンスとして適している設計をメリットデメリット含め考えて、納得行く方で組んであげる

ということかなと自分の中ではまとまりました。（メリットデメリット考えるときに、REST など設計にベースとなる考え方が生きてくるという認識）

本書を通じて、Web API 設計および運用のスタンダードを HTTP や REST などベースとなる考え方をさらった上で学ぶことができました。いい復習になりました

基本的にエンジニアリングにするにあたっては、その場その場での当たり前を知っていないと、間違った認識が自分の中でのスタンダードになる可能性があるので、引き続きさまざまな本を読みます。