REST API 过滤器操作符最佳实践 [英] REST API filter operator best practice
问题描述
我正在构建一个使用 filter 参数来控制搜索结果的 REST API.例如，可以通过调用以下方法来搜索用户:
I am building a REST API that uses a filter parameter to control search results. E.g., one could search for a user by calling:
GET /users/?filter=name%3Dfoo
现在，我的 API 应该允许许多不同的 filter 操作符.数字运算符，如equals、大于、小于、字符串运算符等contains、begins with 或 ends with 和 日期运算符，例如 year of 或timediff.此外，AND 和 OR 组合应该是可能的.
基本上，我想支持底层 MySQL 数据库操作符的子集.
Now, my API should allow many different filter operators. Numeric operators such as equals, greater than, less than, string operators like contains, begins with or ends with and date operators such as year of or timediff. Moreover, AND and OR combinations should be possible.
Basically, I want to support a subset of the underlying MySQL database operators.
我发现了很多不同的实现(两个很好的例子是 Google分析和LongJump)似乎使用了自定义语法.
根据我的要求，我可能会设计一个与 MySQL 运算符语法非常相似的自定义语法.
但是，我想知道是否有任何我应该遵循的最佳实践以及我是否应该考虑其他任何事情.谢谢！
I found a lot of different implementations (two good examples are Google Analytics and LongJump) that seem to use custom syntax.
Looking at my requirements, I would probably design a custom syntax pretty similiar to the MySQL operator syntax.
However, I was wondering if there are any best practices established that I should follow and whether I should consider anything else. Thanks!
推荐答案
您需要一种已经存在的查询语言，不要试图重新发明轮子！通过 REST，这是一个复杂且未完全解决的问题.您的应用程序必须满足一些 REST 约束:
You need an already existing query language, don't try to reinvent the wheel! By REST this is complicated and not fully solved issue. There are some REST constraints your application must fulfill:
统一界面/超媒体作为应用状态的引擎:
您必须向您的客户发送超媒体响应，他们必须遵循这些响应中给出的超链接，而不是自己构建请求.因此，您可以将客户端与 URI 的结构分离.
uniform interface / hypermedia as the engine of application state:
You have to send hypermedia responses to your clients, and they have to follow the hyperlinks given in those responses, instead of building the requests on their own. So you can decouple the clients from the structure of the URI.
统一界面/自描述信息:
您必须发送带有语义注释的消息.因此，您可以将客户端与数据结构分离.做到这一点的最佳解决方案是 RDF，例如开放链接数据词汇.如果您不想使用 RDF，那么第二个最佳解决方案是使用供应商特定的 MIME 类型，这样您的消息将是自描述的，但客户需要知道如何解析您的自定义 MIME 类型.
uniform interface / self-descriptive messages:
You have to send messages annotated with semantics. So you can decouple the clients from the data structure. The best solution to do this is RDF with for example open linked data vocabs. If you don't want to use RDF, then the second best solution to use a vendor specific MIME type, so your messages will be self-descriptive, but the clients need to know how to parse your custom MIME type.
要描述简单的搜索链接，您可以使用URI 模板，例如GET/users/{?name} 将等待查询字符串中的 name 参数.您可以使用 hydra 词汇hydra:IRITemplateMapping/a> 为参数添加语义，如 name.
To describe simple search links, you can use URI templates, for example GET /users/{?name} will wait a name parameter in the query string. You can use the hydra:IRITemplateMapping from the hydra vocab to add semantics to the paramers like name.
描述即席查询是一项艰巨的任务.您必须以某种方式描述您的查询可以包含的内容.
Describing ad-hoc queries is a hard task. You have to describe somehow what your query can contain.
You can choose an URI query language and stick with URI templates and probably hydra annotation. There are many already existing URI query languages, like HTSQL, OData query (ppl don't like that one), etc...
您可以选择现有的查询语言并将其发送到单个 URI 参数中.这可以是您想要的任何内容，例如 SQL、SPARQL 等……您必须教您的客户生成该参数.您可以创建自己的词汇来描述实际查询的约束.如果你不需要复杂的东西，这应该不是问题.我不知道描述词汇的现有查询结构，但我从未寻找过它们...
You can choose an existing query language and send it in a single URI param. This can be anything you want, for example SQL, SPARQL, etc... You have to teach your client to generate that param. You can create your own vocab to describe the constraints of the actual query. If you don't need complicated things, this should not be a problem. I don't know of already existing query structure descibing vocabs, but I never looked for them...
您可以选择现有的查询语言并将其发送到 搜索请求.最近的 HTTP 客户端不缓存或支持 Afaik SEARCH.它是由 webdav 定义的.您可以使用正确的 MIME 类型来描述您的查询，并且您可以使用与之前的解决方案相同的词汇.
You can choose an existing query language and send it in the body in a SEARCH request. Afaik SEARCH is not cached or supported by recent HTTP clients. It was defined by webdav. You can describe your query with the proper MIME type, and you can use the same vocab as by the previous solution.
您可以使用 RDF 查询解决方案，例如 SPARQL 端点，或三重模式片段等...因此您的查询将包含语义元数据，而不是您的链接描述.通过 SPARQL，您不需要三重数据存储，您可以将服务器端的查询转换为 SQL 或您使用的任何内容.您可能可以使用 SPIN 来描述查询约束和查询模板，但这是新的对我也是.可能还有其他解决方案来描述 SPARQL 查询结构...
You can use an RDF query solution, for example a SPARQL endpoint, or triple pattern fragments, etc... So your queries will contain the semantic metadata, and not your link description. By SPARQL you don't necessary need a triple data storage, you can translate the queries on server side to SQL, or whatever you use. You can probably use SPIN to describe query constraints and query templates, but that is new for me too. There might be other solutions to describe SPARQL query structures...
总而言之，如果您想要一个真正的 REST 解决方案，您必须向您的客户描述他们如何构建查询以及他们可以使用哪些参数和逻辑运算符.如果没有查询描述，他们将无法为用户生成例如 HTML 表单.如果您不想要 REST 解决方案，则选择一种查询语言，在客户端编写构建器，在服务器上编写解析器，仅此而已.
So to summarize if you want a real REST solution, you have to describe to your clients, how they can construct the queries and what parameters, logical operators they can use. Without query descriptions they won't be able to generate for example a HTML form for the user. If you don't want a REST solution, then pick a query language write a builder on the client, write a parser on the server and that's all.
这篇关于REST API 过滤器操作符最佳实践的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
