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

Question

我们正在编写第一个非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

Answer 1

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