平面 API 与嵌套 API

Question

我正在为管理例如 cmets 和讨论线程设计 API 方案。 我想有一个端点

/discussions/:discussionId

当你GET 它返回一个 cmets 数组加上一些元数据。评论也许可以单独访问

/discussions/:discussionId/comments/:commentId

我还想允许搜索 cmets 以回答以下问题：用户 XYZ 还剩下多少 cmets？必须指定discussionId 是不可行的，所以我想必须有

/comments/:commentId

例如，您可以在其上?q=XYZ。然后还可以通过例如

获取属于讨论的所有 cmets

/comments/:commentId?discussion=discussionId

和上面的端点

/discussions/:discussionId/comments/:commentId

变得多余。最终，一切似乎都倾向于扁平的 API 结构。在野外，我确实看到了很多这样的嵌套端点。

这里的最佳做法是什么？删除嵌套端点？保留两者并处理冗余？或许还有更合适的设计？

Answer 1

我喜欢做的是使用 CQS 原则公开信息。如果您将查询与命令分开，您可以公开专门的合约，这些合约以您的用例使用的方式返回数据。

基本上，这意味着在您的情况下，您可以：

/discussions

...映射到查询处理程序 FindDiscussions()，它为您提供前 x 个讨论和主要属性（标题、作者、cmets 数量等）的列表。

要获取讨论的详细信息：

/discussions/{discussionId}

...映射到查询处理程序 FindDiscussionDetails()，它为您提供讨论的所有详细信息，以及前 x 个 cmets。

获取其他cmets：

/comments/{discussionId}?{other parameters}

...映射到查询处理程序 FindComments()，它为您提供所有 cmets（按日期等过滤）。

要获取用户的 cmets 总数，这是您可以与用户一起存储的信息（非规范化）并获得如下信息：

/users/{userId}

...映射到查询处理程序 FindUserDetails()，它会返回用户详细信息以及 cmets 的总数。无需即时计算，只需在快速查询中获取非规范化值即可。

同样适用于命令。

优点是您可以公开客户对您的用例的需求，仅此而已。

阅读here。