9、API设计决策与质量治理

API设计决策与质量治理

1. API设计决策概述

在API设计过程中，有诸多重要的设计考量因素，这些因素会对API设计的稳定性产生影响。例如，API提供者和客户端常常会面临对（未来）用例的不确定性，这使得一些关键设计难以从一开始就做到完美。

以Lakeside Mutual的API设计师为例，在更新客户状态转换操作的请求场景中，面对聚合客户信息的需求，他们决定将参数树和原子参数模式相结合，以实现一个能展现领域模型所需视图的表达性数据契约，同时接受嵌套树结构必须以可互操作的方式进行序列化和反序列化。

此外，除了概念层面的考量，还需要做出许多技术决策，包括支持的通信协议（如HTTP、HTTPS、AMQP、FTP、SMTP等）和消息交换格式（如JSON、SOAP、普通XML、ASN.1、Protocol Buffers、Apache Avro模式、Apache Thrift等），甚至可以引入API查询语言，如GraphQL。

2. 消息表示模式选择

参数结构的决策定义了请求和响应消息的数据传输表示（DTR），但尚未明确各个表示元素的含义。有四种元素原型模式，为元素原型决策提供了典型的设计选项，具体如下：
| 模式 | 问题 | 解决方案 |
| — | — | — |
| 数据元素（Data Element） | 如何在不暴露提供者内部数据定义的情况下，在API客户端和提供者之间交换领域/应用级信息？如何从数据管理角度解耦API客户端和提供者？ | 为请求和响应消息定义专门的数据元素词汇表，封装和/或映射API实现业务逻辑中相关的数据部分。 |
| 元数据元素（Metadata Element） |