子オブジェクトを投稿し、すべての親のすべての子を取得するためのAPIエンドポイントを設計するにはどうすればよいですか？

たとえば、クライアント、レポートなどのエンティティがあります。クライアントには多くのレポートがある可能性があり、単一のレポート管理のエンドポイントは次のようにネストする必要があると思います。

/clients/{client_id}/reports/{report_id}

1つのクライアントのすべてのレポートに関しては、エンドポイントが期待されます。

/clients/{client_id}/reports

しかし、すべてのクライアントのすべてのレポートを取得して、APIの一貫性と適切な設計を維持するためのエンドポイントをどのように見ればよいか

私のアプローチ：

1. （私はそれをいくつかのgoogle apiで見ました）それの代わりに「-」を使用し、それを「すべて」として解析します：

/clients/-/reports

これはエンドポイントのフォーマットを同じに保ちますが、少し変わって見え、この方法を示唆するrfcを見つけることができません。

2. すべてのレポートのためだけに別のエンドポイントを作成します。

/reports

ただし、クライアントのレポートを取得するには、次のようにします。

/clients/{client_id}/reports

3. エンドポイントをリファクタリングして、「クライアント」を親ではなく、単なるフィルタパラメータにします。

/reports?client={client_id} -1つのクライアントのレポート

/reports -すべてのクライアントのレポート

特定のクライアントのレポートを投稿するための新しいエンドポイントを追加する場合、URLにパラメーターを持つPOSTリクエストになるため、見栄えが悪くなる可能性があります。

他にアイデアの提案はありますか？

しかし、すべてのクライアントのすべてのレポートを取得して、APIの一貫性と適切な設計を維持するためのエンドポイントをどのように見ればよいか

何よりもまず、RESTful APIをモデル化するための黄金律はないことを覚えておいてください。私たちが持っているのは、ベストプラクティスと慣習です。そうは言っても、可能性のある答えは、通常どおり、要件を最もよく満たすもの、この場合はモデルを最もよく表すものを選択します。

したがって、表現力から3つのオプションを確認してください。

＃1「-」表記

これは素晴らしいアイデアです。これにより、reportsに属するすべてのclients状態を表すことができます。「クエリ」を特定のレポートセット（clients境界内にあるレポート）に絞り込みます。

階層（所属）の概念を常に保持しているためreports、別の場所にある場合は、この表記が重要になります。例えば：

• クライアントに属するすべてのレポート /clients/-/reports
• 部門に属するすべてのレポート /departments/-/reports
• 従業員に属するすべてのレポート /employees/-/reports

ただし、システムで使用可能なすべてのレポートを取得するために、階層を維持しても、次のオプションに勝る重要な利点はありません。

＃2異なるURI

利用可能なすべてのレポートを取得するときに境界/コンテキスト/階層を表現する必要がない場合は、このアプローチの方が合理的です。

新しいURI（/reports）は、レポート管理の可能性も残します。ただし、必要と思わない場合は、完全なRESTfulサポートを提供する必要はありません。たとえば、あなたは述べましたMake a separate endpoint just for all the reports。それは結構です、あなたは実装する必要があるだけでGET、クエリのためのいくつかのフィルターもそうです、そしてそれだけです。

あなたはまだこれを行うことができることに注意してください/reports?client={client_id}。同じリソースに別のURIを設定しても問題ありません。私が読んだいくつかの記事では、これを堅牢性と呼んでいます。

＃3階層を元に戻す

このアプローチはあなたの期待に応えられないと感じています。さらに、私は、それが最終的にあなたを出発点に連れて行くと思います。

結論

＃1と＃2は相互に排他的ではないことに注意してください。両方を実装できます。実際の状況とOPの前提によれば、私は＃2のみを実装します。

^{1：それは/clients/-/reports私が推測することと同等です}

GoogleのAPI設計パターンでは、このシナリオで「-」を使用することを推奨しています。

GET /clients/-/reports

ソース：

https://cloud.google.com/apis/design/design_patterns#list_sub-collections