web-dev-qa-db-ja.com

RESTful API命名規則

だから私と私の上司はここで同意しておらず、それに関する情報を見つけることができません。シナリオ：特定の組織のすべてのユーザーを取得したい。 URLはどうあるべきですか？

mydomain.com/users/by/organisation/{orgId}

OR

mydomain.com/organisation/{orgId}/users

私たちの議論：

ケース1：呼び出しは「ユーザー」を返すことが期待されているため、「リソース」（呼び出しの最初の部分）はそれに関連付けられる必要があります。

ケース2：組織はユーザーの「所有」/「の親」であるため、組織を最初にする必要があります。

あなたの考えは何ですか？

PDATE：mydomain.com/{resource}の後に何が来るか心配する必要はありません。質問は主に、HTTPアクション（GET、POST、PUT、DELETE）が最初のリソースmydomain.com/usersに関連する必要があるかどうか、または関係mydomain.com/organisations/users/を反映する必要があるかどうかに関連しています。

restnaming-conventionsrestful-architecture
11
We0

RESTには厳密なルールがないことをご存じでしょう。多かれ少なかれ自由に実装できますが、ここでは2セントです。

mydomain.com/users/by/organisation/{orgId}

ただし、これを読むと何をするかがわかるので、これは良いURLのように聞こえます。これは素晴らしいアイデアではありません。通常、各urlセグメントは、存在するまたは存在できるリソースを指定します。

この場合、usersは1つ以上のリソースを表し、organisationも表しますが、byはそうではありません。APIの機能を明確にするのに役立つのは、Wordにすぎません。

呼び出しは「ユーザー」を返すことが期待されているため、「リソース」（呼び出しの最初の部分）はそれに関連付けられる必要があります。

リソースは必ずしもURLの最初の部分で指定される必要はありません。必要に応じて、2番目、3番目、または10番目にすることができます。

mydomain.com/organisation/{orgId}/users

これはかなり良く見えますが、改善点が1つあると思います。 organisationと一致するように、organisationsをusersに名前変更する必要があります

この

mydomain.com/organisations/{orgId}

次に、ID orgIdの組織を取得し、

mydomain.com/organisations/{orgId}/users

その組織に属するすべてのユーザーを取得します。

さらに絞り込むには、次のようにします

mydomain.com/organisations/{orgId}/users/{userId}

1つの特定の組織に属する1人の特定のユーザーを取得する

PDATE： mydomain.com/{resource}の後に何が来るか心配する必要はありません。 質問は主に以下に関連していますHTTPアクション（GET、POST、PUT、DELETE）最初に関連する必要がありますリソース mydomain.com/users、またはmydomain.com/organisations/users/の関係を反映する必要があるかどうか。

アップデートに回答するには：

私はすでにそれについて上で述べました。 リソースは必ずしもURLの最初の部分で指定されているとは限りません。必要なリソースをURLの後ろに移動することでURLの品質が向上する場合は、先に進んでください。

19
Tim

まず、これから始めましょう。技術的には、それほど重要ではありません。 RESTは、通常の（HTML）Webページのリンクのように、URLがリンクを通じて発見可能でなければならないことを示しています。

ただし、一貫性があり、説明のないURL構造が害を及ぼすことはありません。 URLの階層構造をお勧めします。

  • /organisationsは、すべての組織のリストを返します
  • /organisations/123は特定の組織を返します（＃123）
  • /organisations/123/usersは、その組織に関連付けられているユーザーのリストを返します
  • 等.

代わりに、クエリ文字列をフィルタリングに使用することもできます。

  • /usersは、すべてのユーザーのリストを返します
  • /users?organisation=123は、その組織に関連付けられているユーザーのリストを返します

この階層的な観点からは、/users/by/organisation/123はあまり意味がありません。 /users/by/organisationを呼び出した結果はどうなりますか？または/users/by？

6
Nic Wortel

ここに表示しようとしているものには概念的な違いがあります。 1つ目は、いくつかの基準に基づいた、システム内のすべてのユーザーリソースのフィルタリングです。 2つ目は、組織に属するユーザーリソースを示しています。

2番目のURLは、私が考える組織に属しているユーザーを表示するのに適しています。

最初のURLは、すべてのユーザーから表示するユーザーを効果的にフィルタリングしています。

Urlquerystringを使用することも可能ですが、URLを使用してもフィルタリングには問題ない場合があります。そう

mydomain.com/users?organisationId={orgId}

望ましいかもしれません。 URLにはクエリ文字列を含めることができ、落ち着くことができます。

DELETE mydomain.com/users/organisation/{orgid}は本当に意味がありますか？組織を削除することを期待しますか？そうでない場合、これは実際にはリソースを指しているわけではないため、検索を実行しているので、おそらくクエリ文字列を使用する必要があります。

検索基準をファーストクラスオブジェクトにする、または この質問 または この質問 にある他のフィルタリング手法の1つを使用するなど、検索を実行する他のオプションがあります。

6
Sam Holder

mydomain.com/users/by/organisation/{orgId}

「によって」はどういう意味ですか？それは何の関係もありません。 ランダムな単語をURLに含めない を試してください。

ケース1：呼び出しは「ユーザー」を返すことが期待されているため、「リソース」（呼び出しの最初の部分）はそれに関連付けられる必要があります。

これは、RESTful APIが強制または期待する規則ではありません。業界でもそれほど一般的ではなく、私はたくさんのAPIを扱ってきました。それをフォルダーと考えてください。

  • / users-ユーザーのリスト
  • / users/1-IDが1のユーザー
  • / users/1/organizations-ユーザーが所属する組織
  • / organizations-組織のリスト
  • / organizations/1-組織番号1
  • / organizations/1/users-その組織のユーザー

SOAPまたはa PHP function、しようとしているgetUsersByOrganization($orgId)のように、それはプログラマーのように見えますRESTの仕組み。:)

ケース1（最初のURIセグメント=戻り値の型）に固執する必要がある場合は、次のようにします。

  • / users？orgId = 1

これは完全にRESTfulであり、本質的には単なるフィルターです。両方を行うこともできますが、私はできません。そこには場所のない関係です。私はフィルターを次のようなものに維持しようとします：？active = true

3
Phil Sturgeon

RESTによって、URI構造は人間の観点からのみ重要です。RESTクライアントの観点からは重要ではありません。これは、セマンティクスで注釈が付けられたリンクをたどっているからです。 。

あなたの質問に答えるには、関係やユーザーについて何を説明したいかが重要です。関係を追加および削除する場合は、関係コレクションを定義する必要があります。ユーザーを追加および削除する場合は、ユーザーコレクションを定義する必要があります。これは操作によってのみ問題になります。 GETを使用すると、一連のユーザーを返すクエリを定義できます...

0
inf3rno

二番目は良いです。 URIをたどると、フィルターとして、または親子オブジェクトを表示して、要求が絞り込まれます。ユーザーは組織に属しているため、組織/ユーザーである必要があります。ただし、可能であれば、URIの「組織」レベルも削除します。

mydomain.com/{orgId}/users
0
Pharylon