功能相似的REST API端点命名咨询：图书保存类双端点如何命名

首先说结论：别用版本号给两个端点凑区分名。
API版本号的设计初衷是标记存在不兼容变更的接口迭代关系，简单说就是给老调用方留兼容窗口、给新调用方用新逻辑的场景用的。你这两个端点是并行存在、根本没有新旧替代关系，硬套/v1/book/save、/v2/book/save的写法，会给前端、第三方调用方传递完全错误的信号——人家会默认其中一个是快下线的老接口，平白多出一堆没必要的沟通成本。

可落地的命名思路，全围绕两个端点的真实差异设计就行，完全不需要为了区分硬造路径：

• 优先按业务场景做嵌套路径区分
  既然两个端点从代码层面就没法合并，那底层肯定存在触发主体、使用场景、权限范围的差别，直接把这些差别写在路径里就好。
  举个实际的例子：如果一个是作者上传草稿的保存接口，另一个是运营审核通过后正式上架图书的保存接口，就可以分别命名为/books/draft（POST请求提交保存，返回草稿状态的图书ID）、/books/published（POST请求提交正式上架保存，返回已发布状态的图书ID）。调用方看路径就知道接口的用途，不用翻半天文档猜两个保存接口到底差在哪。
• 按处理规则做属性区分
  如果两个端点的核心差异是保存逻辑不同，比如一个是全字段覆盖式保存（没传的字段就清空），一个是增量补丁式保存（只更新传入的非空字段，其他字段不动），就直接把规则体现在路径里：全量保存用标准资源路径/books（POST），增量保存用/books/partial，路径本身就讲清楚了处理逻辑的差别。
• 顺带修正下不规范的写法
  你之前提到的/book/save本身就不符合REST设计习惯——REST语义里，向资源路径发POST请求本身就代表“在该资源下创建/保存实体”的动作，完全没必要硬加save后缀。刚好借着这次拆端点的机会，把路径调整成资源导向的写法，后面团队维护也省心。

避坑提醒：别为了区分加无意义的后缀，比如/book/save1、/book/save2，或者硬给同一个路径加随机查询参数?saveType=1拆接口。这类写法等于把两个接口的差异全藏在后端代码里，所有调用方都要反复确认才能搞懂什么时候该调哪个，后面排查问题、迭代功能的成本会特别高。

内容的提问来源于stack exchange，提问作者Sxc-Dev