19、服务 API 开发中的关键实践：模型转换、功能表达与偏好支持

服务 API 开发中的关键实践：模型转换、功能表达与偏好支持

在服务 API 的开发过程中，有几个关键方面需要我们特别关注，包括将内部模型转换为外部消息、将内部功能表达为外部动作以及向客户端广告支持的响应偏好。下面将详细介绍这些方面的相关内容。

1. 转换内部模型为外部消息

在服务 API 的实现阶段，将内部模型转换为外部消息是一项重要的工作。以下是一些关键要点：
- 文档记录 ：记录将内部模型转换为外部消息的规则是一个很好的实践。这有助于与其他开发者共享算法，并便于调试过程中发现的错误。但不要将这种表示描述发布给 API 消费者，因为他们不需要了解接口背后的内部数据或对象模型。
- 内部模型变更处理 ：随着时间推移，服务的内部模型可能会发生变化。在很多情况下，这些变化不应导致外部消息的改变。例如，当内部模型属性 user.id 变为 user.identifier 时，无需更改外部属性。但如果内部模型添加了新属性（如 user.hatsize ），在不影响现有 API 消费者的情况下，这些新属性可以反映在外部消息中。不过，在文本/CSV 行末尾添加字段可能没问题，但重新排列字段顺序（如将新字段插入为行中的第一个字段）可能不是个好主意。
- 选择合适的表示格式 ：如果预计内部模型会频繁变化，应选择一种旨在减少此类变化影响的表示格式。例如，Collection+JSON 适合变化的模型（所有属性都表示为 data.name 和