API 入门 (24) 设计 API 的数据——业务实体

在前面的设计过程中，我们已经找出了两个主要的业务实体：自行车和目录，并把他们转换为可以操作的资源。在 API 的消费者和提供者的交互过程中，业务实体的信息（作为请求的参数和响应的返回值）在双方之间进行传递。

我们的下一个小目标就是如何设计 API 的数据。本文重点介绍一个如何设计业务实体的属性的方法。

列出属性

首先，我们要写出一个业务实体的属性，并为每一个属性定义一个用户友好的名字。以 自行车 业务实体为例：

为了保证坚持用户为中心的原则（千万要牢记！），在写业务实体的属性时，可以问问下面的问题：

在列出属性后，我们还有指定属性的数据类型。在为属性选择数据类型时，建议使用可移植的基本数据类型，可以兼容不同的编程语言。常见的基本数据类型有：string，number，date 和 boolean.

现在为 自行车 业务实体添加类型：

在一些场景下，某个业务实体的属性必须存在，才能达成 API 的目标；而在另一些场景下，这个属性不出现，也不影响用户的使用和具体实现。对于 API 的每一个目标，设计者，消费者和研发人员，都有十分清楚业务实体的属性是否是必要的。

现在为 自行车 业务实体添加必要性：

虽然我们要求属性的名称是用户友好的，自描述的，但是有时候很难通过一个词进行描述。这时候，我们可以添加一些额外但描述信息。

最后，使用一张表格，对 自行车 业务实体的属性进行概括。