Json中的最佳API响应格式

Question

哪一个最适合Rest API响应?

1. 在这里我返回一些元信息与实际数据。虽然我不确定他们是否需要使用这些元信息。

{
"version": "1.0.0",
"isError": false,
"statusCode": 200,
"message": "Permission Object",
"data": {
"id": 1,
"name": "user create",
"created_at": "2022-11-30T10:18:20.000000Z"
}
}

2. 在第二个例子中，我只返回相关数据。

{
"id": 1,
"name": "user create",
"created_at": "2022-11-30T10:18:20.000000Z"
}

如果有更好的办法，请给我提个建议。

Answer 1

我注意到您使用了标记REST，所以我假设您正在考虑RESTful API实现，并且对RESTful API设计有一些了解。

如果您需要一些最佳实践，我认为其中有几个是有用的。这里和这里

看了你的例子，我更倾向于第二种选择，原因是:

1. IsError可以由HTTP响应确定，例如400,500,200,201，所以它是冗余的。
2. Status和Message在响应成功时也是冗余的，但在错误状态时可能有用，如在ASP中。. NET，你可以使用ProblemDetails响应(你可以自定义你想要的方式)。

{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Unable to create a new user due to missing name",
"status": 400,
"traceId": "00-0aa7d64ad154a1e1853c413a0def982d-195d3558c90f7876-00"
}

3. version是一个有趣的。通常，它可以包含在请求头或URL中。如果API不能处理请求的版本，那么它应该在问题详细信息中返回错误。

因此，我更喜欢第二个选项，并在出现错误时发送问题详细信息响应。

Answer 2

一个在github上启动超过18K的开源CRM使用Laravel-default api资源项目链接代码示例link

注意状态码参考

这一点非常重要。如果您需要从本文中记住一件事，那可能就是:

你的API可能做的最糟糕的事情是返回一个错误响应200 OK状态码。

这只是糟糕的语义。相反，返回一个正确描述错误类型的有意义的状态码。

仍然，您可能会想，"但是我按照您的建议在响应正文中发送错误详细信息，那么这有什么问题呢?">

让我给你讲个故事。

我曾经不得不使用一个API，它为每个响应返回200 OK，并通过状态字段指示请求是否成功:

{
"status": "success",
"data": {}
}

因此，即使状态是200ok，我也不能绝对确定它没有处理我的请求失败。

这种设计是真正的禁忌，因为它破坏了API和用户之间的信任。你开始担心API可能在欺骗你。

所有这些都是非常不restful的。你应该怎么做呢?

使用状态码，并且只使用响应体来提供错误详细信息。

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Expected at least two items in list."
}

Answer 3

JSON API是与HTTP一起工作的格式。它描述了客户端应该如何从服务器请求或编辑数据，以及服务器应该如何响应这些请求。