AIP-9 术语表

为了简洁起见，这份AIP定义了一些常用术语，而非在每个AIP中单独定义。

指南

以下术语 应当 在各AIP中保持一致。

API

应用程序编程接口。可以是本地接口（如客户端库）或网络接口（定义见下文）。

API后端

一组服务器及相关基础设施，实现API服务的业务逻辑。API后端服务器通常称为API服务器。

API消费者

使用API服务的实体。对于Google API，通常是拥有客户端应用程序或服务器资源的Google项目。

API定义

API的定义，通常在Protocol Buffer服务中定义。API定义可以由任意数量的API服务实现。

API前端

一组服务器及相关基础设施，基于API服务（如负载均衡和身份验证），提供通用功能。API前端服务器通常称为API代理。

注意： API前端和API后端可能部署在一起，也可能分布在不同地方。有时，它们可以编译成一个程序文件，在一个进程中运行。

API方法

API中的独立操作方法。通常使用Protocol Buffers中的 rpc 定义表示，并在大多数编程语言中映射成API中的函数。

API生产者

提供API服务的实体。对于Google API，通常是负责API服务的Google团队。

API产品

API服务及其相关组件，如服务条款、文档、客户端库和服务支持。作为一个API产品向客户展示。例如Google Calendar API。

注意： 人们有时将API产品简称为API。

API服务

一个或多个API实现部署，发布在一个或多个网络地址上，如Cloud Pub/Sub API。

API服务定义

API定义（ .proto 文件）和API服务配置（ .yaml 文件）的组合，用于定义API服务。Google API服务定义的架构是 google.api.Service 。

API服务端点

指API服务用于处理传入API请求的网络地址。一个API服务可能有多个API服务端点，如 https://pubsub.googleapis.com 和 https://content-pubsub.googleapis.com 。

API服务名字

指API服务的逻辑标识符。Google API使用兼容RFC 1035 DNS的名字作为其API服务名字，如 pubsub.googleapis.com 。

API标题

指API服务面向用户的产品标题，如“Cloud Pub/Sub API”。

API请求

对API方法的单次调用。通常用作计费、日志、监控和流控的单位。

API版本

一个或一组（关联）API的版本。API版本通常由字符串组成，如“v1”。并包含在API请求和Protocol Buffers包名称中。

客户端

客户端是调用API执行特定任务的程序，以及以用户可访问的方式发布API或操作离线资源数据的通用工具（如CLI），

客户端的示例包括：

• 命令行界面
• 库，如特定编程语言的SDK
• 从API以JSON格式读取资源并执行操作的脚本
• 工具，如声明式客户端
• 可视化UI，如Web应用程序

Google API

Google服务发布的网络API。大多数托管在 googleapis.com 域。不包含其他类型的API，如客户端库和SDK。

声明式客户端

声明式客户端，也称为基础设施即代码（IaC），指这样一类客户端，它们使用标记语言或代码表示API发布的资源，执行适当的命令式操作，让资源进入指定状态。为了确定需要进行哪些修改，确认更新效果，声明式客户端对比服务器端资源属性和客户端定义的值。这种比较保证了创建或更新操作的准确性，但它要求服务将客户端设置的值作为只读数据谨慎保存。

声明式客户端概况并屏蔽的复杂性包括：

• 为进入特定状态，选择适当的命令式操作（创建/更新/删除）。
• 这些命令式操作的顺序。

Terraform是此类客户端的一个示例。

用户

直接使用API（比如用cURL）的人。定义这个术语是为了区分AIP中的人类 用户 和程序化 客户端 。

网络API

跨计算机网络操作的API。网络API使用包括HTTP在内的网络协议进行通信，通常由与消费者之外的组织提供。

修订记录

• 2024-12-18: 按照开发文档风格，将标题和术语改为小写
• 2024-10-23: 添加API标题条目
• 2023-07-24: 将IaC更名为声明式客户端
• 2023-04-01: 添加IaC定义
• 2023-03-24: 修改格式，支持锚链接