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更具可读性，因为可能存在我们需要放置的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 - include related object details or just ID's

Answer 1

有趣的问题，我确实看到了有办法做到这一点的好处。接口或继承将无法工作，因为你真正返回的只是一个字符串（比喻）。一组帮助器如何作用于某种类型并为您构建响应？您可以传递它T，它将根据您设计的规则和模式通过构建响应的对象进行迭代。你可以有一个GetBuilder（x），它会从你的Get中调用。这为处理退货提供了单一位置，并提供了一致性。

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

1 个答案: