<h2>はじめに</h2>
新プロジェクトで一から API 設計・開発をやる機会があり、それきっかけで読んでみたかった技術書のうちの一つ<a href="https://www.oreilly.co.jp/books/9784873116860/">Web API: The Good Parts</a>を読みました。
感想および個人的見解をまとめていきます。
<h2>読んだ感想・個人的見解</h2>
本技術書は、設計周りだけでなく API を公開することを想定した話が多く納得した点が多くありました。
特に、
<ul>
<li>バージョニングによる後方互換性サポート（クライアント側が最新版に対応していないケースなどを考慮）</li>
<li>コール回数の制限（API サーバへのアクセス過多になるケースを考慮）</li>
<li>セキュリティ面のケア（不正なコールでこちらでは意図していない情報を与えてしまうケースなどを考慮）</li>
</ul>
は一般公開するにあたっては当たり前だけども、普段自分が外部公開をする API を作らないこともあり、勉強になりました。（<del>JSON インジェクションに関しては意識できてなかった。。</del>）
その他、印象に残ったトピックとしては
<blockquote>
設計の際に REST を意識しすぎない
</blockquote>
一例をあげるなら、REST でいう URI はリソース（ある実体があつまった集合体; e.g. posts: 投稿という実体があつまった集合体）であり、それに加えて場合に適した HTTP メソッドを指定してエンドポイントを設計するのが主流だと自分は考えていました。
しかし、検索用の API のエンドポイントに<code>search</code>という動詞を入れてあげて、より用途をわかりやすくしたり、バージョンを含めたりすることでユーザーにどのバージョンを使うのがを明示的に指定してもらったりというケースは現実的にはありえます。これは厳密にいうと、REST に反したケースです。
つまり、REST の考え方に反していたとしても、それがユーザーにとってのわかりやすさや使いやすさをより向上するものであればそれはよいことだと腑に落ちました。
<blockquote>
リクエストもレスポンスもシンプルであれ
</blockquote>
必要以上にフィールドをオブジェクトで包むケースは、使う側の実装の負担になったりそもそも冗長な表現である可能性があるため、できるだけシンプルな階層で送ってもらい、返すことが大事だと再認識しました。
ただ、将来的な設計を考えると、レスポンスに関してはなるべく共通化しておくことは大事だなと感じていて、自分ならなるべく階層はフラットに作りたいけど、共通化の面も考えて一個階層を深く作ってあげます。（以下サンプル）
<pre><code class="language-json">{
 &quot;error&quot;: {
 // エラーの中身はエンドポイントやステータスごとに返したいものを入れる
 },
 &quot;data&quot;: {
 // 成功した時に中身が入り、エンドポイントごとに返したいものを入れる
 }
}
</code></pre>
ですので一番大事なのは、
どういう API を作りたいかというところに立ち返って、リクエスト・レスポンスとして適している設計をメリットデメリット含め考えて、納得行く方で組んであげる
ということかなと自分の中ではまとまりました。（メリットデメリット考えるときに、REST など設計にベースとなる考え方が生きてくるという認識）
<h2>最後に</h2>
本書を通じて、Web API 設計および運用のスタンダードを HTTP や REST などベースとなる考え方をさらった上で学ぶことができました。いい復習になりました
基本的にエンジニアリングにするにあたっては、その場その場での当たり前を知っていないと、間違った認識が自分の中でのスタンダードになる可能性があるので、引き続きさまざまな本を読みます。

# 設計

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