用于搜索单个资源的 RESTful URL 设计

Posted 2023-03-31

【中文标题】用于搜索单个资源的 RESTful URL 设计

【英文标题】：RESTful URL design for searching for a single resource

【发布时间】：2017-02-22 14:02:18

【问题描述】：

关于用于搜索资源的 RESTful URL 设计，有一个 couple 和 questions。我感兴趣的是单个资源的 RESTful URL，而不是资源 ID。

例如，用户有一个 ID 和资源 URL /rest/user/<id>。我想允许通过他们的电子邮件地址搜索单个用户（系统确保它是唯一的）。

我想出的替代方案：

A) /rest/user/email/[e-mail] - 创建一个单独的资源来访问单个资源（尽管 /rest/user/email 将是未定义的）

B) /rest/user/email:[e-mail] - 这里 email:[e-mail] 被认为是用户的替代标识符，因此这是使用替代 ID 的同一资源端点

C) /rest/user?email=[e-mail] - 这是 RESTful 搜索，但它会返回一个包含零个或一个条目的数组，因此不是对资源的直接引用

D) /rest/user/search?email=[e-mail] - 与 (C) 类似的搜索 API，但语义不同

该设计应可扩展为使用系统提供的不同唯一 ID（外部 ID、电话号码、SSN 等）进行搜索。

我倾向于选项 B，因为它定义了一种替代方式来引用特定用户（可以在服务中全局使用）并重用现有资源端点。这可以扩展到 PUT 和 DELETE 以及 GET。但它非常 RESTful 吗？

【问题讨论】：

REST API DESIGN - Getting a resource through REST with different parameters but same url pattern的可能重复

【参考方案1】：

/rest/user/search?email=[e-mail]，斜线'/'用于表示级别关系，例如/rest/customer/orders/order1，客户有订单集合，订单有一个名为order1的订单。