REST API设计：适配器服务如何标记不同流向的端点？

方案1：以数据流向作为端点前缀 #

直接在路径中明确数据的源服务和目标服务，让端点语义一目了然：

• PUT /from-A/to-B/apples：A向X推送苹果数据，X适配后同步给B
• GET /from-A/to-B/apples：B通过X主动拉取A的苹果数据（X完成模型适配后返回B的领域模型）

这种方式的优势是路径完全无歧义，任何人看到端点就能立刻明白数据的流向和交互双方，同时保留了REST方法的语义（PUT用于推送更新，GET用于主动拉取）。

方案2：以服务角色区分端点 #

把适配器X对A和B分别暴露的接口分开，用服务标识作为顶层路径，同时结合资源名：

• 面向服务A的推送接口：PUT /A/outbound/apples（A将自身的苹果数据推送到X的出站接口，X负责适配并同步给B）
• 面向服务B的拉取接口：GET /B/inbound/apples（B从X的入站接口拉取适配后的苹果数据，X从A获取原始数据并转换）

这种设计的好处是清晰划分了X对不同服务的接口职责，outbound和inbound也强化了数据流向的语义。

方案3：利用查询参数辅助区分（适合资源路径需统一的场景） #

如果希望资源路径保持简洁，可通过查询参数明确数据的流向或目标模型，但需确保方法语义和参数配合无歧义：

• PUT /apples?target=B：A推送苹果数据到X，指定目标为B，X适配后同步
• GET /apples?source=A：B从X拉取来自A的苹果数据，X返回适配后的B模型

注意：这种方式需要在API文档中明确参数的约束，避免滥用，仅适合资源名称必须统一的场景。

方案4：基于领域模型标识区分 #

既然A和B的领域模型不同，可以在路径中体现模型类型，明确接口处理的是哪种模型：

• PUT /apples/A-model：A提交自身的苹果模型到X，X适配后同步给B
• GET /apples/B-model：B请求适配后的苹果模型，X从A获取原始数据转换后返回

这种方式直接点明了接口处理的模型类型，从根源上消除了歧义，同时保留了资源的核心名称。

额外建议 #

1. 无论选择哪种方案，都要在API文档中明确每个端点的请求/响应模型类型、数据流向和适配逻辑，避免使用者混淆。
2. 保持方法语义的一致性：PUT/PATCH用于推送更新，GET用于拉取数据，POST用于创建资源（如果有相关场景）。

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