向客户端呈现REST Web服务接口

Question

我的RESTful Web服务中的一个资源执行搜索操作，它有很多标准/参数。

在当前实现中，此搜索条件像字典一样传递，选项助记符作为键。例如。

{'fieldl_greater_equal' : <value>,
 'field2_like' : <value>,
  ...}

问题是：

为客户端引入每个助记符（即系统界面）的允许助记符和允许值列表的最佳方法是什么？

我应该将这些助记符移动到inurl参数吗？

如何使这种资源易于扩展？

有关如何实施此类系统的任何建议和收据？

Web服务正在Python上实现。

Answer 1

第一。 “搜索”几乎可以表示任何意义。有关用户GET请求的用例非常非常清楚。

“搜索”有三个基本选择。

当“搜索”实际上使用主键来标识资源时，您使用路径元素。路径不会改变。这是资源的身份，而不是某种“搜索”。

Fragment非常灵活，但也存在于RESTful URI处理的边缘。你应该避免使用它。

查询字符串是大多数人在想到“搜索”而不是资源的“识别”时所想到的。

但是，您的URL组件可能相当复杂。我在URL中使用了像/in;param1=this;param2=that/这样的语法来提供更灵活的资源识别。我们声称URI会积极（并且始终）定位资源。 “in”意味着包括。排除我们有“前”。

我尽量避免使用?param1=this&param2=that查询字符串来识别资源。我认为它应该用于页码和其他对于识别资源不重要的事情。

无论你做什么，你需要提供一个允许的param名称及其解释的列表。这是“元数据”，您可以实现元数据REST请求。

您定义了一些“/ api”或“/ meta”API，它们提供有关URI的信息，参数以及它们如何组合在一起。

Answer 2

描述REST Web服务的一种方法是提供描述如何访问服务的WADL。有关允许值的描述，您可以使用某种模式定义（JSON或XML），它允许定义这些定义的枚举。

这种方法允许自动验证，而您总是可以提供自由文本描述，并附加说明示例。