RESTful API 设计辩论 : complex query for restful endpoint

Question

我正在为大量报告数据设计一个 RESTful api，我想传递一组复杂的参数，如下面的代码块所示。我在为这个端点使用 POST 和 GET 之间进行辩论。团队成员似乎更喜欢 GET，但我不确定将这些数据作为 GET 参数传递的最佳方式，目前最好的想法是让一个 GET 参数称为 jsonparams 之类的东西，它将包含所有下面的json编码

{
  "filters": 
    [
      {
        "field": "metric-name",
        "gt": (float/int),
        "lt": (float/int)
      },
      {
        "field": "metric-name-2",
        "gt": (float/int),
        "lt": (float/int)
      }
    ],
  "sort": 
    [
      {
        "field": "metic-name",
        "order": "ASC"/"DESC"
      },
      {
        "field": "metic-name-2",
        "order": "ASC"/"DESC"
      }
    ]
  "limit": 100,
  "offset": 0
}

Answer 1

POST 是用于任何未被 HTTP 标准化的操作的方法。检索由 GET 方法标准化，因此使用 POST 检索与潜在资源相对应的信息永远不是 RESTful。从理论上讲，您应该使用 GET，无论您的 URI 变得多么复杂。

但是，由于您正在执行的查询没有可以对其执行 GET 的单个资源，因此使用 POST 似乎没问题，只要您了解缺点并且文档清晰关于它。坦率地说，我认为使用 POST 比将有效负载编码为 JSON + base64 并将其作为纯粹的查询字符串发送要清晰得多。

使用 POST 的真正问题是当人们使用它时避免或阻止使用真实的 URI。在您的情况下，这似乎不是问题，因为您有一个有效的集合 URI，但查询的语义太复杂而难以表达。

如果您决定使用 GET，则有一个问题。虽然 HTTP 规范没有为 URI 建立限制，但大多数实现都有，如果您需要将所有这些参数作为查询字符串提供，您可能会达到该限制。在那种情况下，规避底层实现的限制是 RESTful，只要它与您的应用程序分离。做你想做的事情的约定是使用 POST 方法和你上面描述的有效负载，以及 X-HTTP-Method-Override: GET header 。