json - 如何在输入/输出中保持 FK 的表示一致（RESTful JSON API）

Question

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

在XML中，这非常简单：

响应正文 (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>

请求正文 (POST/PUT/PATCH) - 使用 ID：
```
PATCH /users/321

...&organization=123
```

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

GET /users/?organization=123

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

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

响应正文 (GET)：

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

{
    ...,
    "organization": "/organizations/123"
}
```
请求正文 (POST/PUT/PATCH) - 接受 URI（为了便于阅读，示例未编码）：
```
PATCH /users/321

...&organization=/organizations/123/
```
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

score 0 · Accepted Answer

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

json - 如何在输入/输出中保持 FK 的表示一致（RESTful JSON API）

1 回答 1

Related

Reference