如何使用LIKE标准设计REST API？

Question

我正在设计一个REST API并为"people"创建一个实体:

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的任何示例.

Answer 1

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

如果您需要公开具有各种查询功能的成熟数据存储，您最好坚持我们OData的已知标准。OData 已作为 REST 出售，但许多 REST 头脑都遇到了问题。不管怎样，最终它是有效的，而且 REST 讨论通常会导致分析瘫痪。

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

话虽如此，如果你需要根据很多字段和各种条件进行查询，我会使用OData。