RESTful API设计：电影翻译功能的HTTP动词及路径最佳实践咨询

首先要明确REST设计的核心原则是资源导向，所有路径都应该对应某一类可被定位的资源，避免在路径中加入动作类动词。你之前的顾虑本质是把「翻译」当成了待执行的动作，而实际上接口要返回的是「翻译后的电影内容」这一资源，基于这个核心逻辑可以选择以下两种符合规范的方案：

方案1：GET请求（推荐，适合90%以上场景） #

GET的语义是获取服务端资源，只要你的操作是幂等的（多次请求结果一致）、不会修改服务端存储的资源，就完全符合GET的使用要求，不存在不合理的问题。
具体路径设计可以参考两种形式：

• 复用原有电影资源接口，通过查询参数控制返回翻译版本：

  GET /api/v1/films/{filmId}?translated=true&type={电影类型}&target_lang={目标语言}
  

  这种方式适合翻译内容和原电影内容结构一致的场景，通过参数切换资源的表现形式，还可以利用HTTP缓存机制减少重复翻译的资源消耗，响应头补充Content-Language字段标识内容语言会更符合HTTP规范。
• 单独拆分译本作为子资源：

  GET /api/v1/films/{filmId}/translations?type={电影类型}&target_lang={目标语言}
  

  这种方式适合译本需要单独返回元数据（比如翻译人员、翻译时间等）的场景，逻辑层级更清晰。

方案2：POST请求（适合实时计算、无持久化存储的场景） #

如果你的翻译是实时计算生成、不会在服务端持久化存储译本，且计算成本较高不适合用缓存，完全可以使用POST请求，REST规范并没有限定POST只能用于创建资源，也可以用于执行单次处理类操作。
路径设计如下：

POST /api/v1/films/{filmId}/translation-tasks

请求体中传入电影类型、目标语言等参数，同步场景下直接返回翻译结果，异步场景下可以返回任务ID供后续查询执行进度。

你之前两个设计的问题说明 #

• http://foo/api/v1/translated/films 不符合资源层级逻辑，译本是从属于单个电影的子资源，不适合作为顶级资源放在路径最前面
• api/v1/films/name/translate 路径中出现了动作动词translate，违反了REST资源导向的设计原则

内容的提问来源于stack exchange，提问作者Dr Schizo