概要

Web APIの設計と構築に焦点を当てた書籍です。

Web APIの重要性、さまざまな利用パターン、そして「美しい」API設計がいかに開発者の生産性やサービスの信頼性を高めるかについて詳述しています。特に、URIの設計原則、HTTPメソッドの適切な利用、およびクエリパラメータを用いた検索やデータ取得といった、API構築における具体的な手法と注意点が解説されています。

同僚に勧められたのと、オススメ本としてもよく見かけていた本なので読んでみました。 2014年発売で10年以上経っていますが、APIの基礎としては色褪せない内容がしっかりと体系化されており、非常に良い本でした。

一方で書いてあるツールや情報が古く、初心者としては間違った情報が入ってこないか心配になりました。自身の知っているプラクティスなどはしっかりと書かれていたので、原理原則になるような箇所を主に読みました。逆にツール名が出てきたところは生成AIの文章を読む感覚で、間違っているかも？くらいの感じで読んだりしました。

印象に残ったところ

理解しやすいURIにするための2つ目のポイントは、APIでよく使われている英単語を利用するということです。たとえ英語を使っていても一般的にAPIでよく使われる語彙を使っているかどうかでわかりやすさは異なってくるでしょう。

ここでの気づきとしては、わかりやすい命名をするためには先人が積み上げてきた暗黙的なコンテキストを含んだ単語を利用することが重要ということです。

例えばgetとfetchは大元では「取得する」ですが、元々の英語のニュアンスの違いからさらに意味を持ち、以下のように解釈されることが多い気がします。

get → すぐ返る、キャッシュやDBのような近い場所から取る
fetch → 外部サービスやネットワーク越しで遅延がある場所から取る

意味がほぼ同じなら、同じ単語でもAPIのパスはわかりやすいものになると思います。特定の単語がよりわかりやすいのは、元々単語が持つ以上の意味（暗黙的なコンテキスト）が付与されているからなんだろうなと思いました。

以下も良い例だと思っています。

InstagramやTwitter、FoursquareのAPIは検索のためのエンドポイントにsearchという単語が入っていました。しかしそもそも「検索する」という行為は動詞であり、URIをリソースと表すものとするデザインでいえばやや王道を外れます。そうした意味においてsearchという単語を入れるべきかは大いに悩ましいところです。しかしわかりやすさの観点で言うと、このエンドポイントは「検索」のためのものであり、全リストを取得するためのものではありませんよ、ということを示すためであればsearchという単語を入れるのはありではないかと思います。

後から見出された法則に違反する単語があったとしても、暗黙的コンテキストをすでに持った単語を使った方がわかりやすいという考えかと思います。

良い命名をするためには、業界にある暗黙的なコンテキストを持つ単語を学ぶことが重要なんだろうなぁと思いました.