Zalando RESTful API 指南：元信息规范详解
项目地址: https://gitcode.com/gh_mirrors/re/restful-api-guidelines 前言
在构建RESTful API时，元信息的规范定义是确保API可管理、可维护的基础。Zalando的RESTful API指南对API元信息提出了明确要求，本文将深入解析这些规范，帮助开发者理解如何正确设计API元信息。
API元信息核心要素
必须包含的基础元信息
每个API规范必须包含以下OpenAPI元信息：
-
标题(title)
作为API的唯一功能描述性名称，应简洁明了地反映API用途。例如"订单服务API"比"服务API"更具描述性。 -
版本(version)
必须遵循语义化版本控制规范（后文详述），用于区分API规范版本。 -
描述(description)
应包含API的详细功能描述，帮助开发者快速理解API用途。 -
联系信息(contact)
包含负责团队的联系方式（名称、URL、邮箱），便于问题追踪。
必须包含的扩展属性
除基础信息外，还必须提供以下扩展属性：
-
API标识符(x-api-id)
全局唯一且不可变的API标识符（后文详述）。 -
目标受众(x-audience)
定义API的目标使用群体（后文详述）。
语义化版本控制规范
版本格式要求
API版本必须遵循语义化版本控制2.0规范，格式为<主版本>.<次版本>.<补丁版本>：
- 主版本(MAJOR)：当进行不兼容的API变更时递增
- 次版本(MINOR)：当以向后兼容的方式新增功能时递增
- 补丁版本(PATCH)：进行不影响功能的错误修复或编辑性修改时可选择递增
特殊说明
-
初始开发阶段
建议使用0.y.z版本号表示API处于初始设计阶段。 -
版本限制
不得使用预发布版本(如1.0.0-alpha)和构建元数据(如1.0.0+20130313)。 -
补丁版本
对于文档修正等小变更，是否递增补丁版本由API设计者自行决定。
示例
openapi: 3.0.1
info:
title: 包裹服务API
description: 用于...的API
version: 1.3.7
API标识符规范
标识符要求
每个API必须提供全局唯一且不可变的标识符，定义在OpenAPI规范的info块中：
/info/x-api-id:
type: string
format: urn
pattern: ^[a-z0-9][a-z0-9-:.]{6,62}[a-z0-9]$
description: |
必需的全局唯一且不可变的API标识符。该ID允许追踪API规范的演进历史和版本序列。
设计建议
-
UUID推荐
建议使用新生成的UUID作为API标识符，避免因API演进而产生修改冲动。 -
复制警告
复制API时，必须立即更改其中的API标识符。
示例
openapi: 3.0.1
info:
x-api-id: d0184f38-b98d-11e7-9c56-68f728c1ba70
title: 包裹服务API
version: 1.5.8
API目标受众分类
受众等级
API必须按目标受众分类，不同等级对应不同的设计标准：
-
组件内部(component-internal)
同一功能组件内部使用的API，通常由特定团队拥有。 -
业务单元内部(business-unit-internal)
同一业务单元产品组合内部使用的API。 -
公司内部(company-internal)
同一公司各业务单元间使用的API。 -
外部合作伙伴(external-partner)
公司业务合作伙伴可访问的API。 -
公共外部(external-public)
任何互联网用户均可访问的API。
规范定义
/info/x-audience:
type: string
x-extensible-enum:
- component-internal
- business-unit-internal
- company-internal
- external-partner
- external-public
description: |
API的预期目标受众。与设计文档质量、评审、可发现性、可变性和权限授予标准相关。
重要原则
-
单一受众
每个API规范只能定义一个目标受众，更小范围的受众已隐含包含在更大范围中。 -
拆分建议
若API不同部分面向不同受众，建议按受众拆分API规范。
示例
openapi: 3.0.1
info:
x-audience: company-internal
title: 包裹辅助服务API
version: 1.2.4
功能命名规范
命名结构
功能命名是统一应用景观中资源命名的重要方式，基本结构为：
<功能域名>-<功能组件名>
其中：
- 功能域名：功能组件所属的功能组
- 功能组件名：API所属功能组件的唯一短标识
受众对应要求
| 要求等级 | 适用受众 |
|---|---|
| 必须(must) | 公共外部、外部合作伙伴 |
| 应当(should) | 公司内部、业务单元内部 |
| 可以(may) | 组件内部 |
注册要求
在使用功能名前，必须通过功能名注册系统进行注册，以确保唯一性。
主机名命名规范
标准格式
API主机名应遵循功能命名规范：
<功能名>.zalandoapis.com
传统格式（已弃用）
仅允许用于组件内部API的传统格式：
<应用ID>.<组织单元>.zalan.do
例外情况
某些面向外部合作伙伴的遗留API主机名可能不符合此规则，这些例外情况会被维护在允许列表中。
总结
Zalando的RESTful API元信息规范为API设计提供了清晰的标准，从版本控制、唯一标识到目标受众分类，每个方面都考虑了API全生命周期的管理需求。遵循这些规范不仅能提高API的一致性，还能增强API的可维护性和可发现性。开发者应根据API的实际使用场景，选择合适的元信息配置，确保API从设计之初就具备良好的管理基础。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
