json - 使用 HAL 设计 RESTful API - 序列化模型关系

Question

我对 REST 比较陌生，但我一直在做关于 RESTful 应该如何做的功课。现在我正在尝试创建一个 RESTful api，为我的模型实现 JSON+HAL 序列化器，这些模型与其他模型有关系。
python中的示例模型:

class Category(Model):
    name = CharField()
    parent = ManyToOneField(Category)
    categories = OneToManyField(Category)
    products = ManyToManyField(Product)

class Product(Model):
    name = CharField()
    price = DecimalField()
    related = ManyToManyField(Product)
    categories = ManyToManyField(Category)

假设我们有一个类别“目录”和一个子类别“食物”，产品“汉堡”和“热狗”都是相关的。
第一个问题。类别和产品应该是资源，所以它们需要一个 URI，我应该在我的模型中实现一个 uri 字段并将其存储在数据库中还是在运行时以某种方式计算它，那么多个标识符(URI)呢？
第二个问题。可发现性，在 Hal 格式中，“GET/”和不同节点应该返回什么以使 api 易于自我发现。

{
  "_links":{
    "self":{
      "href":"/"
    },
    "categories":[
      {
        "href":"/catalog"
      }
    ]
  }
}

第三个问题。添加为属性、嵌入或链接。示例“GET/catalog/food”:

{
  "_links":{
    "self":{
      "href":"/catalog/food"
    }
  },
  "name":"food",
  "parent":"/catalog",
  "categories":[],
  "products":[
    "/products/burger",
    "/products/hot-dog"
  ]
}

{
  "_links":{
    "self":{
      "href":"/catalog/food"
    },
    "parent":{
      "href":"/catalog"
    },
    "categories":[

    ],
    "products":[
      {
        "href":"/products/burger"
      },
      {
        "href":"/products/hot-dog"
      }
    ]
  },
  "name":"food"
}

{
  "_links":{
    "self":{
      "href":"/catalog/food"
    }
  },
  "name":"food",
  "_embedded":{
    "parent":{
      "_links":{
        "self":{
          "href":"/catalog"
        }
      },
      "name":"catalog",
      ...
    },
    "categories":[

    ],
    "products":[
      {
        "_links":{
          "self":{
            "href":"/products/burger"
          }
        },
        "name":"burger",
        ...
      },
      {
        "_links":{
          "self":{
            "href":"/products/hot-dog"
          }
        },
        "name":"hot-dog",
        ...
      }
    ]
  }
}

第四个问题。返回结构时我应该走多深。示例“GET/目录

{
  "_links":{
    "self":{
      "href":"/catalog"
    }
  },
  "name":"catalog",
  "parent":null,
  "categories":[
    {
      "name":"food",
      "parent":{...},
      "categories":[],
      "products":[
        {
          "name":"burger",
          "price":"",
          "categories":[...],
          "related":[...]
        },
        {
          "name":"hot-dog",
          "price":"",
          "categories":[...],
          "related":[...]
        }
      ]
    }
  ],
  "products": []
}

Answer 1

关于第一个问题 :我不会将 URI 存储在数据库中。您可以在运行时轻松地在 Controller 内部计算它们，并且 Controller 有责任关心 URI。通过这种方式，您可以保持模型和 API 解耦，并且如果您决定将来更改 API 结构，则无需使用新的 URI 更新整个数据库。

关于多个标识符，我不确定问题是什么，但同样，在我看来，它与数据库无关，路由和 Controller 应该关心如何处理任何 URI。

关于第二个问题 :首先，作为旁注:我会将单词类别保留为 URI 的一部分。例如，我有 http://domain.com/api/categories/catalog/food .通过这种方式，您可以使您的 API 更具描述性和“可破解性”，这意味着用户应该能够删除 /catalog/food部分并期望收到包含所有可用类别的集合。

现在，关于什么GET应该返回以允许可发现性:我认为已经从您的 URI 结构中清楚地表明了这一点。当用户点击 GET /categories他希望得到一个包含类别的列表(每个类别的名称和 URI，以保持轻量级)，并且当他遵循一个 URI 时，例如 GET /categories/catalog他应该会收到资源 catalog这是一个类别。同样，当他想GET /products/burger ，他应该会收到一个产品资源，其中包含您模型中的所有属性。您可能需要查看 this example关于你的回答的结构。

关于第三个问题 :再次，the same example可以帮助你形成结构。我认为您的第二种回应方式更接近于此，但我还要添加 name领域，不仅是href .

关于第四个问题 :当GET request 需要一组资源(如 GET /categories )我建议只提供每个资源所需的，即每个资源的名称和 URI，并且只有当用户遵循所需的 URI 时，他才能收到其余信息。

在您的示例中，catalog是资源，以此类推 GET /categories/catalog我当然会包括 name资源(目录)及其自链接，以及 parent , sub-categories和 products与之相关的，我只想提供每个的名称和 URI，以保持轻松。 但是 :这是关于设计 API 的一般想法。在您的实际问题中，您应该根据您的具体业务问题来决定。我的意思是，如果您的 API 是关于带有类别和菜肴的餐厅菜单，您可能希望包含价格或简短描述，即使不是针对实际产品而是针对产品集合做出响应，因为可能对于您的用户来说，这就是一个重要信息。所以一般来说，在响应资源列表时提供所有必要的信息(你只知道这些信息是什么)，并在响应特定资源时提供资源的所有详细信息。