8

我正在设计一个 REST API 并有一个“人”的实体：

GET http://localhost/api/people

返回系统中所有人员的列表

GET http://localhost/api/people/1

返回 id 为 1 的人。

GET http://localhost/api/people?forename=john&surname=smith

返回所有姓名和姓氏相匹配的人，但我还有一个进一步的要求。例如，允许 API 使用者检索名字以“jo”开头的所有人的最干净/最佳实践方式是什么。

我见过一些 API 这样做：

GET http://localhost/api/people?forename=jo~&surname=smith

其中波浪号表示“模糊”匹配。另一方面，我已经看到它以完全不同的标准实现，例如

GET http://localhost/api/people?forename-startswith=jo&surname=smith

考虑到我可能有 -endswith、-contains、-soundslike（对于某种 soundex 匹配），这似乎有点麻烦。

任何人都可以从经验中提出更好的建议，以及任何具有类似功能的精心设计的 REST API 示例。

4

4 回答 4

4

恕我直言，您是否有模糊匹配或 -endswith -contains 等并不重要。重要的是您的 REST API 是否允许轻松解析此类参数，以便您可以定义函数以从数据源（DB 或 xml 文件等）获取数据。） 因此

如果您使用的是 PHP……根据我的经验，SlimFramework是一个轻量级、易于上手的解决方案。

于 2012-09-11T13:41:55.597 回答
3

我会向您推荐提供Query String Options的OData 协议。你所做的没问题，并且遵循 REST 约定。

但是，OData 协议描述的是一个$expand参数，甚至是一个$filter参数。此$前缀表示“系统查询选项”，您将对最后一个感兴趣，因为它允许您编写以下 URI：

http://services.odata.org/Northwind/Northwind.svc/Customers?$filter=tolower(CompanyName) eq 'foobar' &select=FirstName,LastName&$orderby=Name desc

它允许您传递类似 SQL 的数据，它可以是您所描述的一个很好的替代方案（两种解决方案都很好，这只是一个品味问题）。

于 2012-09-11T13:43:18.803 回答
2

AFAIK，以上都不是很RESTful。它们都依赖于客户端关于如何调用查询的先验知识（在第一种情况下是查询模式，在第二种情况下是查询 DSL）。实际上，在第二个示例中，API 被简化为数据存储的包装器。因此，API 没有定义服务器域——它是一个数据提供者。这与REST的客户端-服务器约束形成对比。

如果您需要公开具有所有各种查询功能的完整数据存储，您最好坚持我们拥有的已知标准OData。OData 已作为 REST 出售，但许多 REST 负责人都遇到了问题。无论如何，归根结底，它是有效的，而 REST 讨论通常会导致分析瘫痪。

如果我这样做，我可能会将 API 限制为一个常见的用例，所以更像是第二个而不定义查询 DSL（因此是 forenameStartsWith 而不是 forename-startswith）。

话虽如此，如果您需要基于多个字段和各种条件进行查询，我会使用 OData。

于 2012-09-11T15:31:17.613 回答
0

这两个示例都使用查询参数进行过滤。我认为调用这些查询参数或者是否使用了某些通配符语法并不重要。

两种方法都同样 RESTFul。

于 2012-09-11T13:39:41.040 回答