web-dev-qa-db-ja.com

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

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

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

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

/clients/{client_id}/reports

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

私のアプローチ：

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

/clients/-/reports

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

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

/reports

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

/clients/{client_id}/reports

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

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

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

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

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

restapiapi-design
12
Yann

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

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

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

＃1「-」表記

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

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

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

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

＃2異なるURI

boundaries/contexts/hierarchyを取得する際に利用可能なすべてのレポートを表す必要がない場合、このアプローチの方が合理的です。

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

これは/reports?client={client_id}でも可能です。同じリソースに別のURIを設定しても問題ありません。私が読んだいくつかの記事はこれをrobustnessと呼んでいます。

＃3階層を元に戻す

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

結論

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

1：/clients/-/reportsと同等

3
Laiv

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

GET /clients/-/reports

ソース：

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

0
wfg4