はじめに

Web API の設計に関する基本的な考え方を理解するために、「Web API: The Good Parts」を読んでいます。

書籍の記述だけでは上手く腹落ちしなかった箇所で、追加で調べたことがタイトルに合致する内容であれば、こちらに追記していきます。

API エンドポイント（URI）の設計

Web API におけるエンドポイントは、API にアクセスするための URI を指します。

基本的には、URI が「リソース」を指すものであり、URI と HTTP メソッドの組み合わせで処理の内容を表すのが良い設計であるとされています。
これは、HTTP の URI がリソースを指すことで「名詞」として考え、それに HTTP メソッドを「動詞」として組み合わせることで、シンプルに行いたいことを表現することができるからです。

良い設計に近づけるために気をつけなければならないことを、いくつか記載します。
（追記するべきことがあれば、追記していきたいと思っています）

URI が短く入力しやすくなっているか？

短くてシンプルな URI にしておくと、以下のような良いことがあります。

わかりやすい
覚えやすい
入力間違いが少ない

URI は人間が読んで理解できるか？

URI だけで何を目的としたものが理解できることが重要です。

勘違いによるトラブルを防ぐため。
ドキュメントの参照頻度を減らすため。

また、この観点で気をつけたいのは、**「短い URI を目指すがあまり、意味がわかりにくくなってしまうことの防止」**です。

省略表現の扱いについて

慣れてる人にしか伝わらない省略表現をむやみに使うことは避けたほうが良いと思います。

ただし、省略表現そのものがだめというわけではなく、「jp」や「jpn」のように国際規格ISO 3166-1で標準化されたものは、こちらを使った方がわかりやすいこともあるので、ここは内容を見て判断する必要があります。

URI に大文字小文字が混在していないか？

標準的に選択されているのは小文字なので、小文字で統一する方が好ましいです。

大文字小文字が混在していると、間違えやすくなるため。

URI は外部の人も使いやすいか？

サーバ側の都合はサーバサイドで処理をするようにして、Web API の利用者にそれを意識させない設計の方が好ましいです。

URI にサーバ側のアーキテクチャの都合が含まれていないか？

Web API を提供するサーバがどの言語で API を実装しているかや、システム構成などの情報が API の利用者に伝わらない方が好ましいです。

API の利用者にとっては不要な情報であるため。
広く周知された脆弱性が含まれている場合などで特に、攻撃を受ける可能性が高まるため。

URI のルールは統一されているか？

URI に利用される単語や、 URI の構造は統一感がある方が好ましいです。

統一感がない場合、クライアント側の実装時に混乱を招きやすいため。

適切な HTTP メソッドを利用しているか？

HTTP メソッドは「動詞」として表現するため、適切なものを使用する方が好ましいです。

メソッド名	説明
GET	リソースの取得
POST	リソースの登録（リソース名は指定しない）
PUT	リソースの登録/更新（リソース名を指定する）
DELETE	リソースの削除
PATCH	リソースの一部変更
HEAD	リソースのメタ情報の取得

POST と PUT の使い分け

POST と PUT の使い分けは、 URI の指定の仕方にあリます。

POST /photos とすると、リソース名がサーバ側で割り振られて、GET /photos/25252などの新しい URI がアクセス可能になります。一方、 PUT は、PUT /photos/25252のように、使用者がリソースを指定する場合に使います。

PUT と PATCH の使い分け

PUT はデータを完全に上書きしたい場合に使います。
PATCH はデータの一部だけを更新したい場合に使います。

URI で利用される名詞は複数形になっているか？

URI でリソースを表現する場合、リソース名は users や photos のように、複数形の方が適切であるとされています。
これは、データベースのテーブル名が複数形の方が適切であると言われることと同じで、リソースも「集合」を表すものであるため、複数形の方が適切だとされています。

URI にスペースやエンコードが必要な文字が使われていないか？

パーセントエンコーディングされる文字や、スペースは利用しない方が好ましいです。

パーセントエンコーディング

パーセントエンコーディングは、URI において使用できない文字を使う際に行われるエンコード（一種のエスケープ）です。
パーセントエンコーディングされると、元の文字がひと目でわからなくなってしまいます。

URI で単語をつなげる必要がある場合にハイフンを利用しているか？

もっとも良いのは、単語をつなぎ合わせることを極力避けることとされています。

しかし、やむを得ず単語をつなげなければならない場合もあると思います。
その場合、特にポリシーがなければ、ハイフンで繋ぐのが良いという意見が多いようです。
Hyphen, underscore, or camelCase as word delimiter in URIs?

参考

Web API: The Good Parts