はじめに
今更感MAXですが、Web API設計のポイントについて、基礎的なところを聞かれることがあったので雑にメモとしてまとめます。
Web APIに関する仕様
HTTPステータスコードやJSONなど、Web APIに関する技術は、RFC等で標準化されているので、何か迷うことがあれば立ち返りましょう。
https://developer.mozilla.org/ja/docs/Web/HTTP/Resources_and_specifications
https://standards.rest/
エンドポイントの名称が名詞かつ複数形になっているか
基本的にエンドポイントの名称は名詞かつ複数形です。
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
HTTPステータスコードは適切なものになっているか
500エラーでまとめてしまったりすると、障害時の切り分けで困りますので、適切なものをセットしましょう。
単語が連なる場合、ケバブケース（ハイフン区切り）になっているか
どっちでも良いみたいな記事もありますが、Google検索セントラルが推奨していたり、有名どころのWebサービスはケバブケース（ハイフン）になっているので、こちらを推奨。
https://hoge.co.jp/fuga-piyo
参考