API 入门 (25) 设计 API 的数据——响应数据

在上一篇文章中，我们掌握了如何设计业务实体的数据结构，接下来，我们以业务实体的数据结构为基础，继续设计响应和参数的数据结构。

从 API 设计之初，我们就注意到，同一个业务实体（资源），会出现在不同的场景（目标）中。以目录资源为例。在添加自行车的时候，服务会返回已添加的自行车信息；在查询目录的时候，服务也会返回自行车信息。那么，在这两个场景中，自行车的信息是相同的吗？

添加自行车

添加自行车成功后，用户希望看到已经添加的自行车信息，作为操作完成后的验证。此时，响应的数据应该包含全部的自行车信息，都需要向展示用户。

1. 编号：reference
2. 名称：name
3. 价格：price
4. 重量：weight
5. 上架日期：dateAdded
6. 描述：description

在目录中查询自行车

在目录中查询自行车，响应的数据可能包含多个自行车信息。是否需要显示自行车的全部属性信息呢？一般情况下，我们用列表展示满足条件的自行车信息。列表中的信息足以区分不同的自行车就可以了，不需要看到全部的自行车信息。

1. 编号：reference
2. 名称：name
3. 价格：price
   4. 重量：weight
   5. 上架日期：dateAdded
   6. 描述：description

小结

在设计响应的数据结构时，为了帮助我们识别用户真正需要的信息，我们可以回答下面三个问题：

1. 所有属性都与客户业务相关吗？
2. 所有属性都是客户需要的吗？
3. 客户理解所有属性的含义吗？