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

Question

执行搜索操作的RESTfull Web服务中的资源之一有很多标准/参数。

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

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

的问题是：

什么是引入允许助记符和允许值的列表，每个助记符（即系统接口）给我的客户的最佳方式是什么？

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

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

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

Web服务正在Python上实现。

Answer 1

首先。 “搜索”几乎意味着任何事情。它有助于非常清楚GET请求的用例。

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

• 查询字符串。 ?param1=this&param2=that

• 片段。 #param1=this&param2=that

• URL路径元素。 /this/that

路径元素是你真正使用主键时，“搜索”是确定的资源使用的东西。路径不会改变。这是资源的特征，而不是某种“搜索”。

片段是非常灵活的，但也生活在RESTful URI处理的边缘。你应该避免使用它。

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

但是，您的URL组件可能相当复杂。我在URL中使用了一个类似/in;param1=this;param2=that/的语法来提供更灵活的资源识别。我们声称URI会积极地（并且总是）找到资源。 “in”意思是包括。我们有“ex”排除。

我尽量避免使用?param1=this&param2=that查询字符串来标识资源。我认为它应该用它的页码和那些不识别的资源所必需的其他东西。

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

可以定义一些“/ API”或“/元”的API，其提供这一切组合在一起的URI的，参数以及信息。

Answer 2

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

此方法将允许自动验证，而您随时可以提供自由文本说明以及说明示例。