Question

我正在设计一个RESTful API，需要对设计提出第二意见。为了更好地理解，我将抽象出问题陈述。

考虑一个URI /search?key1=value1&key2=value2，它可能会为key1和key2的给定搜索条件返回一个巨大的结果集。

我的任务是确保服务器和客户端受限制，以防止性能下降。如果达到该限制并且在结果集中找不到预期数据，则将要求用户优化搜索查询以缩小范围。（我不是考虑分页，而是考虑不同的问题集）

方法是允许客户端指定服务器（客户端）可以轻松处理的限制，并帮助服务器为自己设置限制，以防止生成影响性能的巨大结果集。

客户可以/search?key1=value1&key2=value2&maxresults=xxxx指定其限制。

服务器可以将其自己的限制设置为搜索URI的配置参数。在提供请求时，服务器将花费一分钟（客户端限制，服务器限制）并生成满足有效限制的结果集。

生成的JSON将有一个元数据部分，它将提及结果是否被截断，以及有效限制集。客户端可以检查此部分并要求用户优化搜索，如果＆＃34;截断＆＃34;是＆＃34;是＆＃34;。问题域实际上允许用户优化为单个项目。

{
    "result": {
        "truncated": "true",
        "limit": "2000",
        "data": [
            {
                "id": "1"
            },
            {
                "id": "2"
            }
            ...
            {
                "id": "2000"
            }            
        ]
    }
}

我想回答的问题是：

这违反了任何REST原则吗？
我可能会遵循标准惯例吗？
您可以引用公共API上的好例子吗？（Jira RESTful API有几个例子）
这个设计中是否有任何可能影响我们未来的问题？

任何关于此的观点都将受到赞赏......

谢谢！

Answer 1

从我的观点来看，这非常符合REST原则。我建议不要将结果大小元数据值添加到响应有效负载，而是添加为HTTP标头。而不是

{
    "result": {
        "truncated": "true",
        "limit": "2000",
        "data": [
            {
                "id": "1"
            },
            {
                "id": "2"
            }
            ...
            {
                "id": "2000"
            }            
        ]
    }
}

该服务将发送

{
    "data": [
        {
            "id": "1"
        },
        {
            "id": "2"
        }
        ...
        {
            "id": "2000"
        }            
    ]
}

并添加其他自定义HTTP标头

x-result-truncated:1
x-result-limit:1000

这种方法的好处是，从客户的角度来看，不属于有效载荷一部分的元数据值会在您的响应的元数据部分中发送，例如传输content-type。

另一个好处是，将元数据打包到HTTP头中也可以重用于其他服务，并且您不必更改返回的有效负载的模式，这意味着客户端可以按预期继续工作（除了某些结果可能是截短的）。

RESTful API，用于保护服务器和客户端免受大型数据集的攻击

1 个答案: