向客户端呈现REST webservice接口

Question

我的restfullweb服务中的一个资源执行搜索操作，它有很多条件/参数。在

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

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

问题是：

向我的客户介绍允许的助记符列表和每个助记符的允许值的最佳方法是什么？在

我应该把这些助记符移到inurl参数吗？在

如何使这样的资源更容易扩展？在

关于如何实施这一制度有何建议和收据？在

Web服务正在Python上实现。在

Answer 1

首先。”搜索“几乎意味着任何事情。非常非常清楚地了解GET请求的用例是什么有帮助的。在

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

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

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

• URL路径元素。/this/that

Path元素是在“search”真正使用主键来标识资源时使用的元素。道路不会改变。这是资源的身份，而不是某种“搜索”。在

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

当大多数人想到资源的“搜索”而不是“标识”时，他们会想到查询字符串。在

然而，你的URL组件可能相当复杂。我在URL中使用了/in;param1=this;param2=that/这样的语法来提供更灵活的资源标识。我们声称URI将肯定（并且始终）定位资源。“in”的意思是包括。我们用“前”来表示排除。在

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

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

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

Answer 2

描述REST web服务的一种方法是提供一个WADL来描述如何访问服务。对于允许值的描述，可以使用某种模式定义（JSON或XML），允许定义这些值的枚举。在

这种方法将允许自动验证，而您始终可以提供一个自由文本描述，并举例说明。在