在上一篇文章中,我们掌握了如何设计业务实体的数据结构,接下来,我们以业务实体的数据结构为基础,继续设计响应和参数的数据结构。
从 API 设计之初,我们就注意到,同一个业务实体(资源),会出现在不同的场景(目标)中。以目录资源为例。在添加自行车的时候,服务会返回已添加的自行车信息;在查询目录的时候,服务也会返回自行车信息。那么,在这两个场景中,自行车的信息是相同的吗?
添加自行车
添加自行车成功后,用户希望看到已经添加的自行车信息,作为操作完成后的验证。此时,响应的数据应该包含全部的自行车信息,都需要向展示用户。
- 编号:reference
- 名称:name
- 价格:price
- 重量:weight
- 上架日期:dateAdded
- 描述:description
在目录中查询自行车
在目录中查询自行车,响应的数据可能包含多个自行车信息。是否需要显示自行车的全部属性信息呢?一般情况下,我们用列表展示满足条件的自行车信息。列表中的信息足以区分不同的自行车就可以了,不需要看到全部的自行车信息。
- 编号:reference
- 名称:name
- 价格:price
4. 重量:weight
5. 上架日期:dateAdded
6. 描述:description
小结
在设计响应的数据结构时,为了帮助我们识别用户真正需要的信息,我们可以回答下面三个问题:
- 所有属性都与客户业务相关吗?
- 所有属性都是客户需要的吗?
- 客户理解所有属性的含义吗?