如何在API的查询字符串中设计泛型过滤运算符？

Question

null

/events?properties.name=Harry&properties.address.city.neq=Washington

但是，如果事件的属性可以由用户定义，则会遇到一个问题，即使用普通相等运算符的Address.city.neq属性和使用不相等运算符的Address.city属性之间可能发生冲突。

示例：Stripe的API

/events?properties.name=Harry&properties.address.city+neq=Washington

此示例与第一个示例类似，不同的是它使用+分隔符（相当于空格）进行操作，而不是.，这样就不会有混淆，因为我的域中的键不能包含空格。

/events?properties.name=Harry&properties.address.city=neq:Washington

/events?filter=properties.name==Harry;properties.address.city!=Washington

此示例使用单个顶级查询参数filter来命名下的所有筛选逻辑。这很好，因为您不必担心顶级名称空间冲突。（尽管在我的例子中，所有自定义都嵌套在属性下。所以这首先不是一个问题。）

但是这样做的代价是，当您想要进行基本的等式筛选时，要键入一个更难的查询字符串，这可能会导致大多数时间都必须检查文档。并且依赖于运算符的符号可能会导致诸如“near”、“invent”或“contains”等不明显的操作的混淆。

示例：Google Analytics的API

/events?filter=properties.name eq Harry; properties.address.city neq Washington

/events?filter[1][key]=properties.name&filter[1][eq]=Harry&filter[2][key]=properties.address.city&filter[2][neq]=Washington

Answer 1

我可能不会回答“哪一个最好”的问题，但我至少可以给你一些见解和其他的例子来考虑。

首先，您讨论的是“具有内容和可由用户定义的模式的通用API”。

这听起来很像solr/elasticsearch，它们都是Apache Lucene上的高级包装器，主要是索引和聚合文档。

GET /_search
{
  "query": { 
    "bool": { 
      "must": [
        { "match": { "title":   "Search"        }}, 
        { "match": { "content": "Elasticsearch" }}  
      ],
      "filter": [ 
        { "term":  { "status": "published" }}, 
        { "range": { "publish_date": { "gte": "2015-01-01" }}} 
      ]
    }
  }
}

q=*:*&fq={!cache=false cost=5}inStock:true&fq={!frange l=1 u=4 cache=false cost=50}sqrt(popularity)

关于我的经历。我们在这两层之上实现了另一层，我们采用了第四种方法。实际上，我认为#4和#5应该同时得到支持。为什么？因为无论你选择什么，人们都会抱怨，而且既然你将拥有自己的“微DSL”，那么你不妨为你的关键字支持更多的别名。

为什么不是2号？内部只有一个筛选器参数和查询，您就可以完全控制DSL。在我们制作我们的资源半年后，我们得到了“简单”的特性请求--逻辑或和括号()。查询参数基本上是和操作的列表，逻辑的或（如City=London或Age>25）并不适合这里。另一方面，括号将嵌套引入DSL结构中，这也是平面查询字符串结构中的一个问题。

好吧，这些是我们偶然发现的问题，你的案子可能不一样。但是仍然值得考虑的是，对这个API的未来期望是什么。