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

Question

什么是更好的设计实践？

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

我是否应该根据请求api.example.org/cars/1仅响应这些资源的ID(因此,如果有人需要有关它们的详细信息,则需要另外的API调用api.example.org/type/1)

{
    "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调用中检索(在本例中为类型).

Answer 1

这涉及REST的核心原则之一,称为HATEOAS(超媒体作为应用程序状态的引擎).

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

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