Question

我正在寻找一种将搜索表示为RESTful uri的正确方法。

我有两种模式：国家和州，国家/地区都有州。

表示搜索具有id或name属性的国家/地区的正确方法是什么？

api/countries/1/id

api/countries/Italy/name

或

api/countries?id=1

api/countries?name=Italy

另外，如果我想查看状态列表？

api/countries/1/id/states

api/countries/Italy/name/states

由于

Answer 1

对于这两个模型即。 countries和states，我认为遵循Uri模式是最合适的。

所有国家/地区：api/country
特定国家/地区：api/country/{England}
所有国家：api/country/{England}/State
特定州：api/country/{England}/State/{Berkshire}

在上面的示例中{}内的值表示变量。

Answer 2

这取决于你的口味。两种变体都可以。

对于州，可以创建新的终点

api/states/name/Italy

Answer 3

您的方法，在REST URL中使用名称是错误的。该名称只是该国家/地区的属性而非子资源，这意味着您不应在URL中看到它。但是，可以选择将其用作密钥，在这种情况下，可以使用名称值代替ID。

api/countries/Italy

我认为你想要实现的目的是过滤字段，即只获取名称：

api/countries/Italy/states?fields=name

或者，如果您预定义某些格式

api/countries/Italy/states?format=onlyName

Answer 4

表示搜索具有ID或名称属性的国家/地区的正确方法是什么？

tl; dr：变体一是混淆的秘诀。如果必须选择，请使用查询字符串进行搜索。

就REST清单而言，URI逻辑仅仅是一个实现细节 - 唯一的问题是该位置的访问机制不能随着时间的推移而中断。内容可以被清空或移动 - 但是URI必须始终在服务端点处，该服务端点为客户端提供他们理解并且可以采取行动的预响应（即，客户端重新发送3 **重定向或超媒体）。

然而，许多成功且设计良好的API试图暴露出一种固有的一致逻辑，旨在直观地探索。因此，您的第一个示例api/countries/1/id实际上是 BAD ，关于开发人员的体验和市场成功，因为它使用起来很混乱：

从查看URI，您不知道您正在运行（可能是CPU /内存昂贵的）搜索而不是检索单个资源
许多公共API遵循资源层次结构和公开URI之间的逻辑映射 - 因此常见的期望是api/countries/1/id检索{1}（无意义查询）或api/countries/1/name给出{Italy}。

因此，查询字符串是一个很好的选择 - 尤其是提供搜索功能。人们可以从单词中看到含义;）

api/countries?name=Italy 
api/countries?q=name(Ital*)              // same result
api/countries?q=isoCode=(IT)             // same result

--> api/countries/1/states               // list all states of Italy
    api/states?q=country/name(Italy)     // - same -
    api/states?q=country/id(1)           // - same -

请求的响应主体只能通过查看URI来预测，这很好。更好的是：它有助于区分资源和视图。＆＃34;视图＆＃34;在查询字符串中定义，可以视为镜头或过滤器，通过它您可以查看其他资源（您的国家/地区集合）的摘录。

这种模式在这些方面同样出色，也常见：

api/countries/search/Italy
api/countries/search/name=Italy
api/countries/search/isoCode=IT,name=*aly

选择这个的原因可能围绕构建API时的实际实现细节 - 因为它分离了对搜索操作的资源的直接访问 - 满足请求所需的CPU /内存，以及响应计数和格式可能是根本不同的。

RESTful URI设计

4 个答案: