RESTful 服务和命名约定

Question

我的实体名为Item。

POST     /api/items          create a new Item
PUT      /api/items/{id}     update an existing Item
GET      /api/items/{id}     get Item by id

但是，我需要以三种不同的模式检索项目：最近的（按纬度、经度和距离)、Favorite（由 isFavorite 标志标记）和 个人（由用户插入）。

虽然我可以命名这三个 URL：

GET      /api/items/nearest?latitude=xxx&longitude=xxx&distance=xxx
GET      /api/items/favorite
GET      /api/items/personal

但是当我读到这可能违反 REST 命名约定时。我应该使用类型参数（某种枚举）吗？但是这样用户就可以调用GET /api/items?type=favorite&latitude=xxx&longitude=xxx&distance=xxx，这是没有意义的。

最后一个问题：Twitter API 似乎不遵守 REST 命名约定，端点像 POST statuses/update 或 GET direct_messages/sent。你怎么看？

Answer 1

REST 不是一个标准——它是一个概念，所以实际上你不能粗暴地违反它。

但在您的情况下，我建议再添加一条 GET 路线

GET /api/items?type=favorite|personal|nearest&...

并将您的“模式”作为获取查询传递，而不是将其与 id 混合使用

Answer 2

REST 没有 URI 命名约定。

我看到的支持问题

GET /api/items/{id} 
GET /api/items/favorite

这会让客户感到困惑吗，因为有时/items 之后的路径段是表示单个资源的 id，有时是表示组资源的名称。

我看到的支持问题

GET /api/items?type=favorite&latitude=xxx&longitude=xxx&distance=xxx

正如您所认识到的，在某些查询参数可能会或可能不会应用于结果的情况下，让客户端进行令人困惑的调用是有问题的。

在我看来，问题实际上是最近的项目，因为这需要一组在其他上下文中没有意义的查询参数。另一种选择是使用单独的顶级端点。

GET /api/items/{id}?favorite=true&personal=false
GET /api/nearest-items/latitude=xxx&longitude=xxx&distance=xxx
    [optional ?favorite and ?personal query params] 

请注意，如果您添加其他一些也需要多个查询参数的选择条件，这将非常糟糕。

编辑-----

嗯。另一种选择是将三个可选的最近参数混合为一个。

GET /api/items?nearestTo=12.34,54.40,5&favorite=true

这不太适合人类阅读，但人类真的会阅读您的 URI 吗？