良いエンドポイントを意識すると使用者にとって理解しやすく、使いやすいAPIを提供できます。
また、実装者にとってもメンテナンスしやすく、不具合の温床を防ぐことにも繋がります。 そのようなAPIを実装するためには、「どのようなエンドポイントが良いのか」を理解する必要があります。
短くて入力しやすい
短くて入力しやすいということはシンプルで覚えやすいことに繋がります。使用者にとって使いやすいAPIと言えるでしょう。
x https://api.example.com/service/api/search o https://api.example.com/search
人間が読んで理解できる
そのURLを見ただけで、それ以外の情報がなくてもそれが何を目的としたものなのかがある程度わかるようにしておくことが良いでしょう。 そのためには単語を無闇矢鱈に省略したりしないことです。
x https://api.example.com/p/12345 o https://api.example.com/products/12345
大文字小文字が混在していない
大文字小文字が混在するとAPIがわかりづらくなり、間違いのもとに繋がります。デファクトスタンダードである小文字に統一することが良いでしょう。
x https://api.example.com/USERS/12345 o https://api.example.com/users/12345
サーバー側のアーキテクチャが反映されていない
サーバー側がどのようなアーキテクチャを使用してアプリケーションを実装しているかの情報は使用者には全く関係のない情報ですのでURIには反映させないほうが良いでしょう。
また、アーキテクチャが変更された際にURIも変更することになり、使用者・実装者ともに手間が増えてしまいます。
x https://api.example.com/cgi-bin/get_user.php?user=100
ルールが統一されている
URIの構造などのルールが統一されていないと、使用者にとっては誤解を招きやすくトラブルの温床となってしまいます。
例えばid情報をクエリパラメータに載せるのか、URIに載せるのか、単数形なのか、複数形なのかなどのルールを統一させておく必要があります。
# ルールが統一されていない例 https://api.example.com/products?id=100 https://api.example.com/products/100/reservation
