web-dev-qa-db-ja.com

REST API DESIGN-異なるパラメーターで同じURLパターンを使用してリソースをRESTで取得する

REST url design。に関連する質問があります。関連する投稿をここで見つけました： 同じリソースの異なるRESTful表現 そしてここ： RESTful url toさまざまなフィールドでリソースを取得する しかし、ベストプラクティスとその理由についての回答は明確ではありません。以下に例を示します。

REST「ユーザー」リソースを表すURL。IDまたはメールアドレスを持つユーザーを取得できますが、URL表現は両方で同じままです。多くのブログと私は、人々がこれをさまざまな方法で行っていることを知っています。

この実践を本で読んだり、stackoverflowのどこかで読んだりします（リンクが見つからないようです）

GET /users/id={id}
GET /users/email={email}

多くのブログでこのプラクティスを読んでください

GET /users/{id}
GET /users/email/{email}

クエリパラメータは通常、URLで表されるリソースの結果をフィルタリングするために使用されますが、このプラクティスも使用されているのを見てきました

GET /users?id={id}
GET /users?email={email}

私の質問は、これらのすべてのプラクティスのうち、APIを使用する開発者にとって最も理にかなっているのはどれですか、そしてその理由は何ですか？ REST urlのデザインと命名規則に関しては明確なルールは設定されていないと思いますが、開発者がAPIをよりよく理解できるようにするためにどのルートを取るべきかを知りたかっただけです。

すべての助けに感謝！

resturljax-rsurl-schemeurl-pattern
64
shahshi15

私の経験では、_GET /users/{id} GET /users/email/{email}_が最も一般的なアプローチです。また、提供されたidまたはemailを持つユーザーが存在しない場合、メソッドが404 Not Foundを返すことを期待します。 _GET /users/id/{id}_が表示されることも驚くことではありません（私の意見では冗長ですが）。

他のアプローチに関するコメント

  1. _GET /users/id={id} GET /users/email={email}_
    • 私はこれを見たことはないと思います。もし見たなら、それは非常に混乱するでしょう。パスパラメータを使用してクエリパラメータを模倣しようとしているようです。
  2. _GET /users?id={id} GET /users?email={email}_
    • フィルタリングにクエリパラメータを使用することについて言及したとき、頭に釘を打ったと思います。
    • bothでidとemail（例えば_GET /users?id={id}&email={email}_）？そうでない場合、このような単一のリソースメソッドは使用しません。
    • フィルタリング用のオプションのクエリパラメータを持つユーザーのlistを取得するためにこのメソッドを期待しますが、id、emailまたはパラメーターに含まれる一意の識別子。例：_GET /users?status=BANNED_は禁止ユーザーのリストを返す場合があります。

関連する質問から この回答 を確認してください。

81
DannyMo

これを実用的に見ると、ユーザーのコレクションがあります：

/users   # this returns many

各ユーザーには専用のリソースロケーションがあります。

/users/{id}    # this returns one

ユーザーを検索する方法もいくつかあります。

/users?email={email}
/users?name=*bob*

これらはすべて/ usersに対するクエリパラメータであるため、1のリストであっても、すべてリストを返す必要があります。

実用的なRESTful API設計に関するブログ記事をここに書きました。これについては、とりわけ、ここで次のように語っています。 http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

32
Vinay Sahni

ユーザーリソースについて

パス/usersでは、常にコレクションリソースが返されます。

パス/users/[user_id]で、ID [user_id]を持つユーザーを表すシングルトンリソースを取得するか、要求された[user_id]を持つユーザーが存在しない場合は404応答を取得します（許可されていない場合は禁止（401）要求されたユーザーリソースなどにアクセスします。各リソースパスには1つの識別子のみがあり、これを使用してリソースを検索/識別します。同じリソースパス上の同じリソースに対して複数の識別子を使用することはできません。応答で返されるリソースを取得する場合、その識別子は、リソースを検索/識別するための自己HREFとして応答に含まれます。

GET/queryパラメーターを使用して、パス/usersを照会できます。これにより、要求された基準を満たすユーザーのコレクションが返されます。返されるコレクションには、ユーザーリソースが含まれ、すべてが自己HREFを識別します。

メールリソースについて

あなたが電子メールのために提案したものを見ると、私はむしろ次のように思うでしょう：

ユーザーからのメールもリソースです。したがって、/users/[user_id]/emailsはID user_idのユーザーのメールアドレスのコレクションを返すと思います。 /users/[user_id]/emails/[email_id]は、user_idおよび['email_id']を持つユーザーのメールを返します。識別子として使用するものはあなた次第ですが、私は整数に固執します。削除するメールを識別するパスにDELETEリクエストを送信することにより、ユーザーからメールを削除できます。たとえば、/users/[user_id]/emails/[email_id]のDELETEは、user_idを持つユーザーが所有するemail_idを持つメールを削除します。ほとんどの場合、そのユーザーのみがこの削除操作を実行できます。他のユーザーは401応答を受け取ります。

ユーザーが持つことができるメールアドレスが1つだけの場合は、/users/[user_id]/emailに固執できます。これにより、シングルトンリソースが返されます。ユーザーは、そのURLで新しいメールアドレスをPUTtingまたはPOSTingすることにより、自分のメールアドレスを更新できます。アプリケーションでメールなしのユーザーを許可しない場合、ユーザーがそのURLにDELETEリクエストを送信すると401で応答する必要があります。

2
Wilt