rest - 如何设计api以RESTful风格通过非主键检索一个资源？

Question

原来，我们有一个 api GET/users/:id 来通过它的主键检索一个 user。

现在我们需要一个新的 api 来通过电子邮件检索 user。

GET/users?email=xx@xx.com 好像是获取一个集合。

GET/users/byEmail/:email 包含一个非名词词 byEmail。

还有其他选择吗？

Answer 1

您建议的两种方法本身都是有效的，但我可能不会同时使用这两种方法，因为最好坚持为每个资源使用一个 URI。另一种常见的方法是:

/users/id/:id

或

/users/email/:email

我应该指出，查询参数与 url 参数或 /name/:value 与 /:value 的选择并不是使服务“RESTful”的原因。换句话说，拥有“漂亮”或“可读”的 URL 并不自动意味着您的服务是 RESTful。

REST 的关键点之一是通过 URI 进行资源标识，即特定的 URI 将始终指向特定的资源。对于电子邮件，这可能会改变(用户可能想要更改他们的电子邮件地址)，因此此 url 不再始终标识此用户。

一个更 RESTful 的方法是明确这实际上是一个搜索而不是一个标识符，并且有一个像这样的 URI:

/search/users/email/:email

这更符合 REST 风格，因为此 URI 始终标识相同的资源，即此电子邮件地址的搜索结果。请注意，本例中的资源是搜索结果，而不是用户资源本身。