RESTネストリソースのベストプラクティスは何ですか？

私の知る限り、個々のリソースには正規パスが1つだけ必要です。次の例では、適切なURLパターンは何でしょうか？

例として、会社の残りの表現を取り上げます。この架空の例では、各会社が 0以上の部門を所有し、各部門が 0以上の従業員を所有しています。

関連する会社がなければ、部門は存在できません。

従業員は、関連する部門なしでは存在できません。

これで、リソースパターンの自然な表現がわかります。

• /companies 会社のコレクション -新しい会社のプットを受け入れます。コレクション全体を手に入れよう。
• /companies/{companyId}個々の会社。GET、PUT、DELETEを受け入れる
• /companies/{companyId}/departments新しいアイテムのPOSTを受け入れます。（社内に部門を作成します。）
• /companies/{companyId}/departments/{departmentId}/
• /companies/{companyId}/departments/{departmentId}/employees
• /companies/{companyId}/departments/{departmentId}/employees/{empId}

制約を考えると、各セクションでは、少し深く入れ子にするとこれは理にかなっていると感じます。

ただし、GETすべての会社のすべての従業員をリスト（）にしたい場合、問題が生じます。

そのためのリソースパターンは、/employees（全従業員のコレクション）に最も密接にマッピングされます。

それは、/employees/{empId}もしそうなら、同じリソースを取得するための2つのURIがあるので、私も持っている必要があるということですか？

または、スキーマ全体をフラット化する必要があるかもしれませんが、それは従業員がネストされたトップレベルのオブジェクトであることを意味します。

基本レベルで/employees/?company={companyId}&department={deptId}は、最も深くネストされたパターンとまったく同じ従業員のビューが返されます。

リソースは他のリソースによって所有されているが、個別にクエリ可能でなければならないURLパターンのベストプラクティスは何ですか？

あなたがしたことは正しいです。一般に、同じリソースに対して多くのURIが存在する可能性があります。これを行うべきではないというルールはありません。

そして一般的に、アイテムに直接または他のサブセットとしてアクセスする必要があるかもしれません-そのため、あなたの構造は私にとって意味があります。

従業員が部門の下でアクセスできるからといって：

company/{companyid}/department/{departmentid}/employees

会社の下でもアクセスできないという意味ではありません。

company/{companyid}/employees

その会社の従業員を返すでしょう。それはあなたの消費するクライアントが何を必要としているのかに依存します-それはあなたが設計すべきものです。

しかし、すべてのURLハンドラーが同じバッキングコードを使用してリクエストを満たし、コードが重複しないようにしたいと思います。

ネストされたエンドポイントとネストされていないエンドポイントの両方の設計戦略を試しました。私はそれを見つけました：

1. ネストされたリソースに主キーがあり、親の主キーがない場合、システムが実際にそれを必要としない場合でも、ネストされた構造はそれを取得する必要があります。

2. ネストされたエンドポイントには、通常、冗長なエンドポイントが必要です。つまり、部門全体の従業員のリストを取得できるように、多くの場合、追加の/ employeesエンドポイントが必要になります。/ employeesがある場合、/ companies / departments / employeesは何を購入するのですか？

3. ネストされたエンドポイントはそれほどうまく進化しません。たとえば、今は従業員を検索する必要はないかもしれませんが、後で検索する必要があり、ネストされた構造がある場合は、別のエンドポイントを追加するしかありません。ネストされていないデザインでは、パラメーターを追加するだけで済みます。

4. リソースには、複数のタイプの親が含まれる場合があります。その結果、複数のエンドポイントがすべて同じリソースを返します。

5. 冗長なエンドポイントがあると、ドキュメントの記述が難しくなり、APIの学習も難しくなります。

つまり、ネストされていない設計では、より柔軟で単純なエンドポイントスキーマを使用できるようです。

私が行ったことを質問から、より多くの人々がそれを見る可能性が高い回答に移動しました。

私がやったことは、ネストされたエンドポイントに作成エンドポイントを設定することです。アイテムを変更またはクエリするための正規のエンドポイントは、ネストされたリソースにありません。

したがって、この例では（リソースを変更するエンドポイントをリストするだけです）

• POST /companies/ 新しい会社を作成すると、作成した会社へのリンクが返されます。
• POST /companies/{companyId}/departments 部門が配置されると、新しい部門が作成するリンクが /departments/{departmentId}
• PUT /departments/{departmentId} 部門を変更します
• POST /departments/{deparmentId}/employees 新しい従業員を作成し、へのリンクを返します /employees/{employeeId}

したがって、各コレクションにはルートレベルのリソースがあります。ただし、作成は所有オブジェクト内にあります。

上記の回答はすべて読みましたが、共通の戦略がないようです。Microsoft DocumentsのDesign APIのベストプラクティスに関する良い記事を見つけました。参考にすべきだと思います。

より複雑なシステムでは、クライアントがいくつかのレベルの関係をナビゲートできるようにするURIを提供するのは魅力/customers/1/orders/99/products.的です。代わりに、URIを比較的シンプルに保つようにしてください。アプリケーションがリソースへの参照を取得すると、この参照を使用して、そのリソースに関連するアイテムを検索できるようになります。上記のクエリをURI /customers/1/ordersに置き換えて、顧客1のすべての注文/orders/99/productsを検索してから、この注文で製品を検索できます。

。

ヒント

よりも複雑なリソースURIを要求しないようにします collection/item/collection。

URLの外観はRESTとは関係ありません。何でもあり。これは実際には「実装の詳細」です。変数に名前を付ける方法と同じです。彼らがしなければならないすべては、ユニークで耐久性があります。

これに多くの時間を無駄にしないでください。選択を行い、それに固執する/一貫性を保つだけです。たとえば、階層を使用する場合、すべてのリソースに対してそれを行います。クエリパラメータを使用する場合...コード内の命名規則と同じように。

なんでそうなの ？私が知る限り、「RESTful」APIはブラウズ可能です（ご存知のように...「アプリケーション状態のエンジンとしてのハイパーメディア」）。したがって、APIクライアントは、URLがどのようなものであるかを気にしません有効（デバッグ用の場合を除いて、これらの「フレンドリーなURL」を読み取る必要のあるSEOや人間は存在しません...）

コード内の変数の名前がそうであるように、REST APIでのURLの素晴らしさや理解しやすさは、APIクライアントではなく、API開発者としてのみ興味があります。

最も重要なことは、APIクライアントがメディアタイプを解釈する方法を知っていることです。たとえば、それはそれを知っています：

• メディアタイプには、使用可能な/関連するリンクをリストするリンクプロパティがあります。
• 各リンクは関係によって識別されます（ブラウザがlink [rel = "stylesheet"]がそのスタイルシートを意味するか、rel = favicoがファビコンへのリンクであることを知っているように...）
• そして、それらの関係の意味がわかっています（「会社」は会社の​​リストを意味します。「検索」はリソースのリストを検索するためのテンプレート化されたURLを意味します。「部署」は現在のリソースの部門を意味します）

以下はHTTP交換の例です（記述しやすいため、ボディはyamlにあります）。

リクエスト

GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml

応答：メインリソースへのリンクのリスト（会社、人、何でも...）

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: this is your API's entrypoint (like a homepage)  
links:
  # could be some random path https://api.acme.local/modskmklmkdsml
  # the only thing the API client cares about is the key (or rel) "companies"
  companies: https://api.acme.local/companies
  people: https://api.acme.local/people

リクエスト：企業へのリンク（以前のレスポンスのbody.links.companiesを使用）

GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml

応答：（アイテムの下の）会社の部分的なリスト。リソースには、次の2つの会社を取得するためのリンク（body.links.next）、検索のための他の（テンプレート化された）リンク（body.links.search）などの関連リンクが含まれます。

HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml

# body: representation of a list of companies
links:
  # link to the next page
  next: https://api.acme.local/companies?page=2
  # templated link for search
  search: https://api.acme.local/companies?query={query} 
# you could provide available actions related to this resource
actions:
  add:
    href: https://api.acme.local/companies
    method: POST
items:
  - name: company1
    links:
      self: https://api.acme.local/companies/8er13eo
      # and here is the link to departments
      # again the client only cares about the key department
      department: https://api.acme.local/companies/8er13eo/departments
  - name: company2
    links:
      self: https://api.acme.local/companies/9r13d4l
      # or could be in some other location ! 
      department: https://api2.acme.local/departments?company=8er13eo

したがって、リンク/リレーションの方法を確認すると、URLのパス部分を構造化する方法は、APIクライアントにとって何の価値もありません。また、URLの構造をドキュメントとしてクライアントに伝えている場合は、RESTを実行していません（少なくとも、「リチャードソンの成熟度モデル」によるレベル3ではありません）。

私はこの種の道に同意しません

GET /companies/{companyId}/departments

部門を取得したい場合は、/ departmentsリソースを使用することをお勧めします

GET /departments?companyId=123

私はあなたがcompaniesテーブルとテーブルを持っていると思います、そしてdepartmentsあなたが使うプログラミング言語でそれらをマップするためのクラスがあります。また、部署は会社以外のエンティティに接続できると想定しているため、/ departmentsリソースは簡単で、リソースをテーブルにマッピングしておくと便利です。また、再利用できるため、エンドポイントの数が少なくて済みます。

GET /departments?companyId=123

たとえば、あらゆる種類の検索

GET /departments?name=xxx
GET /departments?companyId=123&name=xxx
etc.

部門を作成する場合は、

POST /departments

リソースを使用し、リクエストの本文に会社IDを含める必要があります（部門を1つの会社にのみリンクできる場合）。

Railsはこれに対するソリューションを提供します：浅いネスト。

ここで他の回答で説明されているように、既知のリソースを直接扱う場合、ネストされたルートを使用する必要がないため、これは良いことだと思います。