rest - さまざまなフィールドでリソースを取得するための RESTful URL

Question

答えを見つけるのに苦労している簡単な質問..

REST Web サービスがあり、設計で url パラメーターを使用していない場合、2 つの異なるキーを指定して同じリソースを返すにはどうすればよいですか?

私が欲しい（そしてすでに実装している）例

/Person/{ID}

期待どおりに人を返します。

今私も欲しい

/Person/{Name}

名前で人を返します。

これは正しい RESTful 形式ですか? それとも次のようなものですか：

/Person/Name/{Name}

Answer 1

1 つのリソースを参照するには、1 つの URI のみを使用する必要があります。複数の URI を持つことは、混乱を招くだけです。あなたの例では、2 人が同じ名前を持っているために混乱が生じます。その場合、彼らはどの個人リソースを参照していますか?

つまり、複数の URI で 1 つのリソースを参照することができますが、「真の」URI 以外の場合は、ステータス コード を使用してクライアントを適切な場所にリダイレクトするだけです301 - Moved Permanently。

個人的には、それをサポートするためにマルチ ID スキームやリダイレクトを実装することはありません。単一の識別スキームを選択し、それに固執します。あなたの API のユーザーはあなたに感謝します。

実際に構築する必要があるのはクエリ API です。そのため、名前をパラメーターとして取り、応答で複数の一致する URI/personFinderを返す可能性のあるリソースのようなものを実装する方法に注目してください。/person/{ID}

Answer 2

技術的には、両方の URI が同じリソースを指している可能性があると思いますが (おそらくそのうちの 1 つを正規リソースとして)、実装の観点からはこれを行いたくないでしょう。ID と名前が重複している場合はどうなりますか?

確かに、クエリ パラメータを使用するのに適した場所のように思えますが、そうしないと主張する場合は、おそらくそうすることができます

person/{ID} 

と

personByName/{Name}

Answer 3

私は一般的に、明確さと一貫性のために、同じエンティティを指す複数の ID を避けるのが最善であるというこの回答に同意します。

しかし、時にはそのような状況が自然に発生します。私が協力している例はポーランドの企業で、納税者番号 (「NIP」番号) または国家事業登録番号 (「KRS」番号) で識別できます。

そのような場合、最初にセカンダリ ID を基準として検索エンドポイントに追加する必要があると思います。したがって、ユーザーはセカンダリ ID とプライマリ ID の間で「変換」できます。

ただし、ユーザーがまだセカンダリ ID でエンティティを直接取得できることを主張し続ける場合 (私たちが経験したように)、別の可能性として、ドキュメントには記載されていない「秘密の」URL を提供し、そのような操作を実行します。これは、それを求める努力をしたユーザーに与えることができます。ドキュメントを読んでいるすべての人ではなく、ユーザーがそれを使用することを決定した場合、あいまいさと混乱の可能性はユーザーにあります。

API メンテナーのあいまいさと混乱に関しては、関連する各 API エンドポイントの先頭で、セカンダリ ID をすぐに検出してプライマリ ID に変換するヘルパー関数を使用することで、これを合理的に最小限に抑えることができると思います。

明らかに、シークレット URL にどのスキームが選択されるかは、通常よりもはるかに重要ではありません。