RESTful风格的GET集合接口是否应当返回元素的完整内容？

API返回字段设计建议 #

通用默认方案：仅返回id、name、description等元数据即可 #

这是RESTful API设计的行业通用惯例，原因如下：

• 降低接口响应开销：如果每个元素的models数组数据量较大，且列表接口一次返回几十上百条数据时，全量返回models会显著增大响应体积，拖慢加载速度、浪费带宽，而绝大多数场景下列表页仅需基础元数据完成列表渲染，不需要用到models内容。
• 接口职责更清晰：列表接口负责返回批量元素的基础信息，单元素详情接口GET /elements/{元素id}负责返回包含models数组在内的完整内容，两类接口各司其职，便于后期维护。

灵活兼容方案：按需返回models内容 #

如果确实存在部分业务场景需要在列表接口同时获取models内容，可以通过可选查询参数实现调用方自主选择：
调用方需要携带models时请求GET /elements?include=models，接口才返回完整models数组，默认请求仍只返回基础元数据，兼顾不同场景的需求。

内容的提问来源于stack exchange，提问作者Vamshi