API 版本管理指区分 API 不同开发版本的方法，用来容纳结构变更、消费变化与底层软件的修改。API 互联且持续演化，文档、需求、协议都需随之更新。没有版本管理或方式不当，长期会对下游服务与产品造成灾难性影响。通常只有发生重大变更时才需要升版本。
版本管理没有唯一正确答案，关键是理解各策略的利弊。本文编译自 Nordic APIs（作者 Nahla Davies，2021），系统对比 Accept 头、URI 路径、查询字符串、子域与自定义 HTTPS 头五种版本化方式。
API 版本管理指区分 API 不同开发版本的方法，用来容纳结构变更、消费变化与底层软件的修改。API 互联且持续演化，文档、需求、协议都需随之更新。没有版本管理或方式不当，长期会对下游服务与产品造成灾难性影响。通常只有发生重大变更时才需要升版本。
服务器通过 Accept 头得知浏览器请求的数据文件格式（MIME 类型）。实现 Accept 头版本化，可在头中附加版本参数，让客户端按指定版本获取响应。适用于「格式版本化」场景。
在 URI 路径中写入版本号，是行业黄金标准——Facebook、Twitter、Airbnb 等以 API 为核心的公司都采用。主版本（破坏性变更）通过 URI 路由到新主机；次版本（非破坏性）通过变更日志通知。若多个版本并行运行，应给客户明确的弃用时间线，引导其迁移到新版。
查询字符串本用于过滤数据，但也可承载版本。例如发布新文章是第一版，修正后是第二版，可用 GET /api/article?v=1 取第一版、?v=2 取第二版。这遵循 REST「用查询字符串过滤资源」的约定，是一种创新用法。
用子域托管 API 的最大好处是可把 API 部署在独立于主站的服务器上，API 管理网关也常通过子域路由。常见子域：api、ws、web services、search、services、secure、apis、app、dev。版本化的子域如 apiv1、api2，虽简单但不如路径法常见。
把版本标识放进 HTTP 头（而非 URL）是主要替代方案，适用于格式版本化或实体版本化。以银行为例：为每类账户设唯一 URL 更简洁，若在 URL 中加格式版本，会把同一实体的每种格式都变成独立资源，且链接处理复杂。部分 API 用规范 URL + 版本专属 URL 解决链接问题。