api - 平面与嵌套 API

Question

我正在设计用于管理评论和讨论线程的 API 方案。我想有一个点

/discussions/:discussionId

当您GET 时，它会返回一组评论和一些元数据。评论也许可以单独访问

/discussions/:discussionId/comments/:commentId

我还想允许搜索评论以便能够回答以下问题:用户 XYZ 留下了多少条评论？必须指定 discussionId 是不可行的，所以我想必须有

/comments/:commentId

例如，您可以在其上?q=XYZ。然后还可以获取属于讨论的所有评论，例如，

/comments/:commentId?discussion=discussionId

和上面的端点

/discussions/:discussionId/comments/:commentId

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

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

Answer 1

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

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

/discussions

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

获取讨论的详细信息:

/discussions/{discussionId}

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

获取其他评论:

/comments/{discussionId}?{other parameters}

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

要获取用户的评论总数，这是您可以与用户一起存储的信息(非规范化)并像这样获取它:

/users/{userId}

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

这同样适用于命令。

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

阅读 here .