web-dev-qa-db-ja.com

RESTful APIルート設計：ネストされたものとネストされていないもの

私の質問は、APIの目的でURLを構築するときにリソースをネストすることの利点についてです。従業員リソースにアクセスするには、次の2つの方法を検討してください。

/api/employees?department=1   # flat

Vs.

/api/departments/1/employees  # nested

ここで、APIからRESTリソースにアクセスするための汎用ライブラリを開発するタスクを検討します。すべてのルートがフラットである場合、そのようなRESTラッパーライブラリは必要なだけですアクセスされているリソースの名前を知るには：

store.query('employees', {department_id:1})   =>   /api/employees?department=1

ただし、ネストされたルートをサポートする場合、このラッパーは、そのようなモデルを参照するためのURLを構築する方法を知るために、ネストされているモデルと他のリソースに関する追加情報を知る必要があります。すべてのモデルが同じ親リソースの下にネストされるわけではなく、一部のモデルでさえまったくネストされないことを考えると、RESTラッパーライブラリには、この余分なものすべてを説明する何らかの構成が必要になりますそうでなければ必要とされないであろう知識。

だから私の質問は：

  • APIのネストされたリソースルートに実際の利点はありますか？ （これはエンドユーザーによって消費されることを意図していないため、よりきれいなURLを持つことによる利益は少なくなります）。

  • リソースURL構築の均一性の欠如をサポートするために導入された余分な労力と複雑さを正当化するために、ネストされたアプローチは、美学を超えて、フラットよりも本当に優れていますか？

参照： https://stackoverflow.com/a/36410780/621809

更新：重要な説明

コメントと回答のいくつかから、1つの側面について十分に明確ではなかったことがわかりました。/employees/5や/departments/1のようなURLで単一のリソースをアドレス指定することに反対していません。私はそれが入れ子になっているとは考えていません。

ネストされたリソースと言うときは、/departments/1/employeesのようなURLを指します。ここで、リソースは常に別のリソースのコンテキスト内でアドレス指定されます。主な問題は、URL構築の場合、ジェネリックライブラリは「従業員は部門の下にネストされている」が「ブランチは何の下にもネストされていない」などの追加情報を知る必要があるという事実です。すべてのリソースをRESTfullyにアドレス指定できれば、フラットな方法でアドレス指定する方法を知る方が簡単で予測可能です。

あなたがそれについて考えるとき、データベースでは、オブジェクトのコレクション（例えば、RDMSのテーブル）に対処する方法を知るために追加の情報を知る必要はありません。従業員のコレクションは、常にdepartments/5/employeesではなくemployeesと呼びます。

restrestful-urlapi-designnested-resourcesnested-routes
16
Ernesto

さらにいくつかのレベルをドリルダウンしたい場合はどうなりますか？

/api/addresses?departmentId=1&employeeId=2&addressId=3

vs

/api/departments/1/employees/2/addresses/3

アドレスエンドポイントが突然パラメータで肥大化しました。

また、 Richardson Maturity Modelレベル を見ている場合、RESTfulAPIはリンクを介して検出できるようになっています。たとえば、トップレベル、たとえば/ api/version（/ 1）から、部門へのリンクがあることがわかります。これがHALブラウザのようなツールでどのように見えるかを次に示します。

"api:department-query": {
  "href": "http://apiname:port/api/departments?pageNumber={pageNumber}&pageSize={pageSize}&sort={sort}"
},
"api:department-by-id": {
  "href": "http://apiname:port/api/departments?departmentId={departmentId}"
}

（最終的にページ形式でそれらすべてを一覧表示する可能性のあるクエリ、またはIDがわかっている場合は、特定の部門に直接移動するパラメーター化されたリンクのいずれか）。

ここでの利点は、クライアントが関係（リンク）名を知っているだけでよいのに対し、サーバーは関係（およびリソース）のURLをほとんど自由に変更できることです。

6
Alexandru Marculescu

モデルとセキュリティに基づいて、2番目のソリューションに投票します。

部門はpathにあり、読み取りまたは書き込みのいずれの場合も、ペイロードにある必要はありません。

従業員の離職を変更する場合は、depIDをペイロードに含めるか、別のエンドポイント（別の助成金付き）/ employees/{ID}を介して含めることができます。

0
Teson