如果包含不同的结构，如何构建 REST API？

Question

目前，我有一个 API 端点需要以 JSON 格式返回项目列表。但是，返回的每个项目都有不同的结构。

例如想想提要 API。但是，API 中每个项目的结构可能非常不同。

返回包含多个项目的 API 响应是否标准 - 每个项目具有不同的结构？

下面是一个虚构的示例，用于显示不同的结构。

示例中的 Store、Candy 和 Personnel 在我的案例中逻辑上是相同的（3 个不同的项目）。然而，底层的结构可能非常不同——具有不同的键值对、不同级别的嵌套等。

{
   "store":{
      "book":[
         {
            "category":"reference",
            "author":"Nigel Rees",
            "title":"Sayings of the Century",
            "price":8.95
         
},
         {
            "category":"fiction",
            "author":"Evelyn Waugh",
            "title":"Sword of Honour",
            "price":12.99
}
      
],
      "bicycle":{
         "color":"red",
         "price":19.95
      
}
   
},
{
      "candy":
         {
            "type":"chocolate",
            "manufacturer":"Hershey's",
            "cost":10.00,
            "reduced_cost": 9.00
         
},
        },
{
      "Personnel":
         {
            "name":"chocolate",
            profile:
            {
               "Key": "Value",
               "Key": "Value",
               something:
               {
                
               "Key": "Value",
               "Key": "Value",
               }
            }
         
},
        },
}

Answer 1

就如何设计有效负载而言，REST 没有严格的规则。但是，在这样做时，显然仍有一些事情需要考虑。在不真正了解您的具体需求的情况下，很难给出具体的建议，但总的来说，在设计 JSON REST API 时，我就是这么想的。

1. 平均而言，我的有效载荷有多大。我们不想在每个请求上传递大量数据。这将使您的应用程序非常缓慢，甚至可能无法在移动设备上使用。对我来说，绝对最坏情况下的限制是 1mb，也许这甚至太高了。如果您发现您的有效负载太大，请将其分解为单独的资源。例如，不要将书籍包含在对您的商店资源的响应中，只需引用可通过 /stores/books/{id}
访问的书籍的唯一 ID
2. 是否足够简单以至于偶然发现资源的人可以理解它的一般用途。 API 越简单，对用户就越有用。如果结构真的很复杂，也许将其分解为多个资源是更好的选择
3. 这一点可以平衡数字 #1。尽量减少获取某条数据的请求数量（仍然考虑上面的其他两点）。将有效负载过度分解为单独的资源也会降低性能。