REST API には、少なくとも 2 つの方法でパラメータを設定できます。
- URLパスの一部として(つまり
/api/resource/parametervalue
) - クエリ引数として(つまり
/api/resource?parameter=value
)
ここでのベストプラクティスは何ですか? 1 を使用する場合と 2 を使用する場合の一般的なガイドラインはありますか?
実際の例: Twitter は間隔を指定するためにクエリ パラメータを使用します。( http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321
)
これらのパラメータを URL パスに配置する方が、より良い設計だと考えられますか?
ベストアンサー1
文書化されたベストプラクティスがあるかどうかはわかりませんが、URL 内のパラメータを配置する場所を決定する際に私が使用するガイドラインをいくつか示します。
オプションのパラメータは、クエリ文字列に挿入するのが簡単な傾向があります。
パラメータ値が既存のリソースに対応していない場合に 404 エラーを返す場合は、パス セグメント パラメータを使用することをお勧めします。たとえば、/customer/232
232 は有効な顧客 ID ではありません。
ただし、パラメータが見つからない場合に空のリストを返したい場合は、クエリ文字列パラメータを使用することをお勧めします。例:/contacts?name=dave
パラメータがURI空間のサブツリー全体に影響する場合は、パスセグメントを使用します。例: 言語パラメータ/en/document/foo.txt
と/document/foo.txt?language=en
一意の識別子は、クエリ パラメータではなくパス セグメントに配置することを好みます。
URIの公式ルールはこのRFC仕様に記載されています。ここ他にも非常に役に立つRFC仕様がある。ここURI をパラメータ化するためのルールを定義します。