RESTful API设计：父资源定位符放请求体是否比放在URI更实用？

两种方案的典型形态 #

首先我们先明确两类设计的常规实现逻辑：

嵌套资源设计（方案一） #

将职位申请作为职位的子资源，路由全部嵌套职位ID：

• 提交职位申请：POST /job-vacancies/{vacancy_id}/applications
• 查询单个申请详情：GET /job-vacancies/{vacancy_id}/applications/{application_id}
• 查询某职位下的所有申请：GET /job-vacancies/{vacancy_id}/applications

顶级资源设计（方案二） #

将职位申请作为独立顶级资源，职位ID通过请求体或查询参数传递：

• 提交职位申请：POST /job-applications，请求体携带job_vacancy_id字段
• 查询单个申请详情：GET /job-applications/{application_id}
• 查询某职位下的所有申请：GET /job-applications?job_vacancy_id={vacancy_id}
• 拓展场景（如用户查自己所有投递）：GET /job-applications?user_id={current_user_id}

实用性对比结论 #

两类设计没有绝对的对错，实用性高低完全匹配你的业务场景，但绝大多数通用招聘类产品的场景下，顶级资源设计的实用性更高。

顶级资源设计的核心优势 #

• 客户端接入成本更低：不需要在所有申请相关的接口调用时都拼接父级职位ID，尤其是跨职位查询申请的场景（求职者查看全部投递记录、HR查看全量待审批申请），不需要额外开发独立接口，直接加查询参数即可实现
• 资源定义更符合REST规范：职位申请本身就是独立的业务实体，有独立的状态流转（初筛、面试、offer、拒绝等），不需要依附职位ID即可完成唯一标识
• 可扩展性更强：后续新增申请相关的操作接口（如安排面试、发起背调等），路由规则可以保持统一，不需要额外嵌套层级
• 服务端逻辑更简洁：权限校验、参数解析逻辑可以集中在申请资源的统一拦截层处理，不需要额外解析URI中的职位ID做重复校验

嵌套资源设计的适用场景 #

只有当你的业务满足以下所有特征时，嵌套设计的实用性才会更高：

• 几乎所有申请相关的操作都严格绑定职位维度，没有跨职位查询申请的业务需求
• 网关层需要直接通过URI字段做权限管控，不需要解析请求体或查询数据库即可完成权限校验

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