“IS NOT SET”子句的 API 格式是什么？

Question

我有一个针对我的服务的查询 API，它看起来像这样（JSON-ish 格式）：

{
   filter: {
            ,attribute2: [val21, val22]
            ,attribute3: []
   }
}

有效地表示 select 数据 WHERE attribute2 in ("val21", "val22") AND attribute3 IS NOT NULL 在 SQL-ish 语法中（意思是，返回的对象设置了属性 3，但我真的不在乎它的值是多少是。SQL 当然不是很擅长表达这一点，因为我的数据是键值存储，其中键可能 "not set" 而不是空值）。

我需要扩展这个 API 才能表达 IS NOT SET 谓词，但我不知道这样做的好方法是什么。

我唯一能想到的就是在请求 API 中添加一个特殊的“NOT_SET”值，这会产生 NOT SET语义；但它看起来真的很笨拙且难以理解：

API 语法可以被认为是 JSON 就其 expressiveness/capability

一个理想的答案是参考一些关于 API 设计的广为接受的规则，以表明它是 "good"。

{
   filter: {
            ,attribute2: [val21, val22]
            ,attribute4: [__NOT_SET__]
   }
}

Answer 1

我的建议是不要尝试使用键值对来表示谓词短语。你应该有更多的灵活性，结构类似于：

{
    filters: [
      { attribute: "attribute2", verb: "IN", values: [val21, val22] },
      { attribute: "attribute2", verb: "NOT IN", values: [val21, val22] },
      { attribute: "attribute4", verb: "IS NOT SET" },
   ]
}

当然，您需要一个动词枚举，并且值必须是可选的。如果需要，您可以稍后添加更多动词，并且您不再对穷人施加太大压力 :。您还可以向客户提供支持的动词列表以及它们采用的类型的数量（如果有），因此客户可以根据需要动态构建 UI。

当然，这是一个重大变化，这可能是也可能不是问题。

“IS NOT SET”子句的 API 格式是什么？

What would be a good API format for “IS NOT SET” clause?

api-design