はじめに

今更感MAXですが、Web API設計のポイントについて、基礎的なところを聞かれることがあったので雑にメモとしてまとめます。

Web APIに関する仕様

HTTPステータスコードやJSONなど、Web APIに関する技術は、RFC等で標準化されているので、何か迷うことがあれば立ち返りましょう。

基本的にエンドポイントの名称は名詞かつ複数形です。

.例

https://hoge.co.jp/users

個人的には以下の記事が一番しっくりきていますので引用させていただきました。

WebAPI におけるエンドポイントはリソースを示しているからです。

「リクエストメソッドと URI の組み合わせ」で「自分が何を要求（リクエスト）しているのか」を示します。

非リソースURLの場合、動詞を使うテクニックもあるみたいです。

リソースの集合体から一意に特定するような場合はパスパラメータを、リソースの集合体から何かを絞り込むような場合はクエリパラメータを使用します。

Webメディアの記事とかが分かりやすいですが、特定のこの記事ってことを表したいのでパスパラメータを使っていたりすると思います。

.例

https://hoge.co.jp/items/hoge

クエリパラメータは以下のように使います。

.例

https://hoge.co.jp/search?id=fuga

オーバーフェッチングやリクエストするデータ量が多すぎてパフォーマンスの問題が発生しそうな場合は、クエリパラメタで対象のデータだけ取得できるような設計を考えましょう。

前者の問題に対しては、fieldsで取得する項目名を指定するケースが多い気がします。

後者では、SQLにそのまま当て嵌められるのでoffsetとlimitで指定してあげると使いやすいです。必要に応じてページ番号方式やカーソル方式を検討します。

.例

https://hoge.co.jp/search?fields=name,adress&offset=50&limit=50

500エラーでまとめてしまったりすると、障害時の切り分けで困りますので、適切なものをセットしましょう。

どっちでも良いみたいな記事もありますが、Google検索セントラルが推奨していたり、有名どころのWebサービスはケバブケース（ハイフン）になっているので、こちらを推奨。

.例

https://hoge.co.jp/fuga-piyo