RESTful APIでパスパラメータとクエリパラメータを使用するのはいつですか？

RESTful APIを非常に予測可能にしたいと考えています。クエリパラメータを使用するのではなく、URIを使用してデータのセグメンテーションを行うタイミングを決定するためのベストプラクティスは何ですか。

ページネーション、並べ替え、およびグループ化をサポートするシステムパラメータは、「？」の後に来るのが理にかなっています。しかし、 'status'や 'region'などのフィールド、またはコレクションをセグメント化するその他の属性についてはどうでしょうか。それらもクエリパラメータになる場合、パスパラメータをいつ使用するかを知る上での経験則は何ですか？

RESTful API設計のベストプラクティスは、パスパラメータを使用して特定の1つまたは複数のリソースを識別し、クエリパラメータを使用してそれらのリソースをソート/フィルタリングすることです。

ここに例があります。CarというエンティティにRESTful APIエンドポイントを実装するとします。エンドポイントは次のように構成します。

GET /cars
GET /cars/:id
POST /cars
PUT /cars/:id
DELETE/cars/:id

この方法では、フェッチするリソースを指定するときにのみパスパラメータを使用しますが、これはリソースのソートやフィルタリングを一切行いません。

次に、GETリクエストに車を色でフィルタリングする機能を追加したいとします。色はリソースではない（リソースのプロパティである）ため、これを行うクエリパラメーターを追加できます。このクエリパラメータを次のようにGET/carsリクエストに追加します。

取得する /cars?color=blue

このエンドポイントは、青い車だけが返されるように実装されます。

構文に関する限り、URL名はすべて小文字にする必要があります。エンティティ名が英語で通常2語の場合、キャメルケースではなくハイフンを使用して単語を区切ります。

例 /two-words

この主題について考える基本的な方法は次のとおりです。

URIは、リソースTYPEの特定のインスタンスを一意に識別するリソース識別子です。人生の他のすべてと同様に、すべてのオブジェクト（あるタイプのインスタンス）には、時間不変または時間的である属性のセットがあります。

上記の例では、自動車は非常に具体的なオブジェクトであり、メーカー、モデル、VINなどの属性があり、変化することはありません。色、サスペンションなどは、時間とともに変化する可能性があります。したがって、時間の経過とともに変化する可能性のある（時間的な）属性を使用してURIをエンコードすると、同じオブジェクトに対して複数のURIが生成される可能性があります。

GET /cars/honda/civic/coupe/{vin}/{color=red}

そして数年後、この同じ車の色が黒に変更された場合：

GET /cars/honda/civic/coupe/{vin}/{color=black}

車のインスタンス自体（オブジェクト）は変更されていません。変更されたのは色だけです。同じオブジェクトインスタンスを指す複数のURIがあると、複数のURIハンドラーを作成する必要があります。これは効率的な設計ではなく、もちろん直感的ではありません。

したがって、URIは決して変更されず、存続期間を通じてそのリソースを一意に識別し続ける部分のみで構成する必要があります。変更される可能性があるものはすべて、クエリパラメータ用に予約する必要があります。

GET /cars/honda/civic/coupe/{vin}?color={black}

結論-ポリモーフィズムを考えてください。

REST APIでは、予測可能なURIを過度に気にする必要はありません。URIの予測可能性の提案そのものが、RESTfulアーキテクチャーの誤解を暗示しています。これは、クライアントが実際にURIを作成する必要があることを前提としています。

ただし、本当のREST APIではなく、「RESTにインスパイアされた」API（Googleドライブのものなど）を作成していると思います。これらの場合、経験則は「パスパラメータ=リソースの識別」と「クエリパラメータ=リソースのソート」です。したがって、問題は、ステータス/リージョンなしでリソースを一意に識別できるかということです。はいの場合、おそらくそのクエリパラメータです。いいえの場合、そのパスパラメータ。

HTH。

かつて、主なリソースであるAPIを設計しましたpeople。通常、ユーザーはフィルターを要求するpeopleため、ユーザーが/people?settlement=urban毎回何かを呼び出すのを防ぐために、/people/urban後で簡単に追加できるように実装しました/people/rural。また、これにより、/people後で役立つすべてのリストにアクセスできます。要するに、私の推論は一般的なサブセットへのパスを追加することでした

ここから：

一般的なクエリのエイリアス

平均的な消費者にとってAPIエクスペリエンスをより快適にするために、条件のセットを簡単にアクセスできるRESTfulパスにパッケージ化することを検討してください。たとえば、上記の最近閉じたチケットのクエリは、次のようにパッケージ化できます。GET /tickets/recently_closed

一般的に言って、リソースに明らかな「階層」がある場合は、次のようにパスパラメータを使用する傾向があります。

/region/state/42

その単一のリソースにステータスがある場合、次のことができます。

/region/state/42/status

ただし、「リージョン」が実際に公開されているリソースの一部ではない場合は、おそらく、ページングと同様に、クエリパラメーターの1つとして属しています（前述のとおり）。

セグメンテーションはより階層的で「かなり」ですが、制限される場合があります。

たとえば、3つのセグメントを持つURLがある場合、それぞれが異なるパラメーターを渡して、メーカー、モデル、色で車を検索します。

www.example.com/search/honda/civic/blue

これは非常にきれいなURLであり、エンドユーザーが覚えやすいものですが、今ではこの構造に固執しています。検索でユーザーがすべての青い車、またはすべてのホンダシビックを検索できるようにしたいとしますか？クエリパラメータは、キーと値のペアを提供するため、これを解決します。だからあなたは渡すことができます：

www.example.com/search?color=blue
www.example.com/search?make=civic

これで、キーを使用して値を参照する方法ができました-クエリコードで「color」または「make」。

より多くのセグメントを使用して、次のような種類のキー値構造を作成することで、これを回避できます。

www.example.com/search/make/honda/model/civic/color/blue

それが理にかなっていると思います

URLの例： /rest/{keyword}

このURLはパスパラメータの例です。このURLデータはを使用して取得できます@PathParam。

URLの例： /rest?keyword=java&limit=10

このURLはクエリパラメータの例です。このURLデータはを使用して取得できます@Queryparam。