API 入门 (26) 设计 API 的数据——查询参数数据

在上一篇文章中，我们设计了响应的数据结构。本文继续介绍如何设计参数的数据结构。

在添加、更新一个自行车资源时，需要将自行车的信息作为参数传递给 API 的操作。那么，这个参数需要包含哪些信息呢？

我们先回顾一下自行车的属性信息，再根据具体的操作进行分析。

自行车的属性：

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

添加自行车

在添加一个新的自行车资源时，自行车的编号属性，是由后端服务根据业务规则生成的，不需要管理员提供。再来看看上架日期。上架日期应该等同于管理员添加自行车时的日期和时间，也不需要管理员手动添加，由后端服务自动添加即可。因此，在添加自行车资源时，需要下列属性作为参数信息：

1. 名称：name
2. 价格：price
3. 重量：weight
4. 描述：description

更新自行车

在更新一个自行车资源时，自行车的编号是需要提供的，API 服务使用他来匹配要更新的自行车。自行车的编号是全局唯一的，自行车与其编号一一对应，不会重复。因此，自行车的编号可以作为路径参数。当然，上架日期也不需要在更新操作中进行修改。如果有必要，可以增加更新日期属性，记录最近一次更新时间。因此，在更新自行车资源时，需要下列属性作为参数信息：

1. 编号：reference
2. 名称：name
3. 价格：price
4. 重量：weight
5. 描述：description

小结

参数数据的设计与响应数据的设计相似，在不同的场景中，使用不同的信息表示业务实体资源。需要注意的是，参数只提供必需的数据，特别是不要提供由后端服务产生的数据。下面三个问题依然对参数数据的设计有帮助：

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