python - 向客户端呈现 REST Web 服务界面

Question

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

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

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

问题是:

向我的客户介绍允许的助记符列表和每个助记符(即系统接口(interface))的允许值的最佳方式是什么？

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

如何让这样的资源易于扩展？

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

Web 服务在 Python 上实现。

Answer 1

首先。 “搜索”几乎可以指任何东西。这有助于非常非常清楚您的 GET 请求的用例。

对于“搜索”，您有三个基本选择。

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

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

• URL 路径元素。 /这个/那个

路径元素是您在“搜索”真正使用主键来识别资源时使用的东西。路径不会改变。这是资源的身份，而不是某种“搜索”。

片段非常灵活，但也处于 RESTful URI 处理的边缘。您可能应该避免使用它。

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

然而，您的 URL 组件可能相当复杂。我在 URL 中使用了类似 /in;param1=this;param2=that/ 的语法来提供更灵活的资源标识。我们声称 URI 会积极(并且始终)定位资源。 “在”的意思是包括。我们用“ex”表示排除。

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

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

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