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 无法处理请求的版本，那么它应该在问题详细信息中返回错误。

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