5

我们正在编写我们的第一个非 XML API，我想询问在 API 中表示相关资源的最佳实践。让我解释一下user资源及其相关资源 - organization.

在XML中，这非常简单：

  1. 响应正文 (GET) - 它包含资源 ID 和 URI：

    GET /users/321/

<?xml version="1.0" encoding="UTF-8" ?>
<user>
    <!-- ... --->
    <organization name="Lorem Ipsum Ltd." href="/organizations/123/">123</organization>
</user>

  2. 请求正文 (POST/PUT/PATCH) - 使用 ID：

    PATCH /users/321

...&organization=123

  3. URI 过滤器- 使用相关资源的 ID：

    GET /users/?organization=123

<?xml version="1.0" encoding="UTF-8" ?>
<users>
    <!-- ... --->
</users>

现在，由于JSON不使用属性，因此它不是 1:1 转换。

  1. 响应正文 (GET)：

    我们没有使用 ID 作为值，而是切换到 URI 以遵守 REST 的连通性原则：

    GET /users/321/

{
    ...,
    "organization": "/organizations/123"
}

  2. 请求正文 (POST/PUT/PATCH) - 接受 URI（为了便于阅读，示例未编码）：

    PATCH /users/321

...&organization=/organizations/123/

  3. URI 过滤器- 为了保持 URI 的干净，我们在通过 GET 参数进行过滤时仍然使用 ID 而不是 URI：

    GET /users/?organization=123

{
    "users": [
        ...
    ]
}

最后一位打破了请求和响应之间值的统一性（ID 与 URI），但我们更喜欢使用 ID 而不是 URI，因为 ID 更具可读性，而且在某些情况下我们需要在其中放入多个值过滤器（例如?organization__in=123,124）。

所以我的问题是，你如何在你的 API 中保持相关资源的请求/响应表示一致？任何最佳实践、标准或只是常识？或者也许上述是不必要的担忧？

编辑：为了澄清，我问的是如何根据 URI 结构（GET 参数）和请求/响应数据的格式来设计 API。我不是在问技术实现。

我们想到的一种方法是切换到更详细的表示形式，为 API 的用户提供更多数据，但它仍然不能解决一致性问题。例子：

GET /users/321/

{
    ...,
    "organization": {
        "ud":   123,
        "name": "Lorem Ipsum Ltd.",
        "uri":  "/organizations/123"
    }
}

注意 - 类似问题（不重复）：REST API - 包含相关对象详细信息或仅包含 ID

4

1 回答 1

0

有趣的问题，我确实看到了这样做的好处。接口或继承将不起作用，因为您真正返回的只是一个字符串（比喻）。一组对类型起作用并为您构建响应的助手怎么样？您可以将它传递给 T，它会根据您设计的规则和模式遍历构建响应的对象。你可以有一个 GetBuilder(x)，它会从你的 Get 中调用。这为处理退货提供了一个单一的位置，并提供了统一性。

于 2013-09-25T13:02:34.590 回答