数据传输对象的 RESTful API 响应

Question

我的应用程序中有以下场景。我以用户身份登录并创建了一个组。有一个 REST api 用于创建组 (POST /groups/api/v1/groups) 并获取组详细信息 (GET /groups/api/v1/groups/{group id})

成功返回的响应不仅仅是组资源的 json 表示。它是一个包含许多其他信息的 DTO（以避免多次调用服务器）

例如，响应可以包括

1. 可以在群组上执行的操作（例如：邀请用户加入群组）以及每个操作需要点击的相应网址

2. 组中的成员数。

3. 小组近期活动

4. 会员资料

等

目前唯一使用 REST api 的客户端是需要额外信息的 UI。如果稍后将 API 公开给开发人员，他们可能不需要返回所有信息。在必须返回包含更多信息的 DTO 的情况下，我们如何处理剩余响应？

在 GET 的静止响应中返回 dto 是一个好的设计还是应该避免？

Answer 1

如果您接受 RESTful HTTP 嘈杂的事实，这会有所帮助。噪声的设计补偿是缓存，您应该尽可能多地使用缓存来节省服务器命中。一个缓存良好的应用程序可以使用多个资源，而不是一个大型资源，因为许多请求永远不会离开客户端。

就您的具体问题而言，请使用expand 查询参数来确定要包含的子对象。您可以进一步指定要包含该子项的哪些属性。例如，

GET /groups/api/v1/groups/12345
{
    "id": 12345,
    "name": "The Magnificent Seven",
    "location": {
        "self": "/groups/api/v1/locations/43"
    }
}

GET /groups/api/v1/groups/12345?expand=location
{
    "id": 12345,
    "name": "The Magnificent Seven",
    "location": {
        "self": "/groups/api/v1/locations/43",
        "longitude": "24°01′N",
        "latitude": "104°40′W"
    }
}

GET /groups/api/v1/groups/12345?expand=location[latitude]
{
    "id": 12345,
    "name": "The Magnificent Seven",
    "location": {
        "self": "/groups/api/v1/locations/43",
        "latitude": "104°40′W"
    }
}

Answer 2

提供比要求更多的数据可能会被证明是有害的，您需要开始向每个人解释为什么要提供如此多的数据。您可以有一个对部分用户保密的查询参数，例如“alldetails=true”，这将提供完整的 DTO。

如果您在 REST 服务器上使用 Java 和 codehaus 或其他一些 JSON 实用程序，您可以使用 mixin 指定要公开的元素。 codehaus 为此提供了“addMixInAnnotations()”。

对 GET 的良好 REST 响应应该有一个标识符、所需的详细信息和 JSON 或 XML 格式的 URL。