Question

更好的设计实践是什么？

如果我有对象A并且它包含一些相关对象，例如我有一个汽车对象，它有各种类型。

我是否应该根据请求api.example.org/cars/1仅对这些资源的ID进行回复（因此，如果有人需要有关他们的详细信息，则api.example.org/type/1需要另一个API调用）

{
    "id": 1,
    "name": "Some Car",
    "types": [
        1,
        2
    ]
}

或提供有关这些资源的详细信息

{
    "id": 1,
    "name": "Some Car",
    "types": [
        {
            "id": 1,
            "name": "Some Type",
            "something": "Blah"
        },
        {
            "id": 2,
            "name": "Some Type",
            "something": "Blah"
        }
    ]
}

或提供可选参数，例如“displayAll”，然后提供带有参数名称的数组，这些参数应在一次API调用中检索（在本例中为 types ）。

Answer 1

这涉及REST的核心原则之一，称为HATEOAS（超媒体作为应用程序状态引擎）。

对象ID对客户来说毫无用处且毫无意义。你怎么用他们？将它们送到搜索功能？构造一个新的URI，并将它们附加到它的末尾？拨打1-800号码并询问如何使用它们？将它们打印在纸上并邮寄给政府机构，以帮助API客户找到他们的下一步？

始终只返回完整的URI。给客户端的ID应始终是URI - 它是唯一标识有问题资源的东西，可用于检索，更新或删除它。

Answer 2

我更喜欢选项1的无参数版本，但我倾向于返回类型资源的位置，以便客户端可以选择是否检索这些资源。

否则，我们不会浏览文档。相反，我们将依赖于一些带外数据，例如事先知道类型的路径。

{
    "id": 1,
    "name": "Some Car",
    "types": [
        {
            "location": "api.example.org/type/1"
        },
        {
            "location": "api.example.org/type/2"
        }
    ]
}

REST API - 包括相关对象详细信息或仅包含ID

2 个答案: