rest - 如何组织需要从给定实体返回所有标题的 API？

Question

我有以下端点，它返回一个实体的页面

/entity?page={page}

但是，我需要另一个端点，它返回一个包含所有实体标题的列表。我需要它，因为有一个下拉过滤器选项，用户可以按标题过滤项目，因此我必须在那里列出所有标题。

我想知道在我的 API 中组织这个的最佳实践是什么。也许只是这样：

/entity/titles

标签： restarchitectureapi-design

Answer 1

从基本的 REST 角度来看，我会从重组开始，我会重组以遵循更标准化的结构。在一般的 REST 思维中，资源应该以复数形式命名，除非请求范围内只有其中一个。基于此，我会提出这些端点

GET /entities/ -> Provides a list of all entities (index action)
GET /entities/:id -> where :id is a URL parameter indicating the ID of the page, Provides the details for a single entity (show action)

有了这个基本结构，你的问题就变得更简单了。如果有效负载entity很小并且您不担心性能，我会收到前端请求GET /entities并提取标题。

如果有效负载entity很大，那么我建议在索引操作中添加一个可选的查询参数：

GET /entities?onlyTitles=true

当此参数为true时，返回的有效负载可以仅限于标题。当省略 orfalse时，返回的有效负载可以是实体的完整有效负载。