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

更好的设计实践是什么？

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

我应该根据要求api.example.org/cars/1仅使用 ID 来响应这些资源（因此，如果有人需要有关这些资源的详细信息，则需要在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 调用中全部检索（在本例中）types).

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

对象 ID 对于客户端来说是无用且无意义的。你用它们做什么？将它们提供给搜索功能？构造一个新的 URI，并将它们附加到其末尾？拨打 1-800 号码并询问如何处理这些号码？将它们打印在纸上并将其邮寄给政府机构来帮助 API 客户找到下一步行动？

始终只返回完整的 URI。提供给客户端的 ID 应该始终是 URI - 它是唯一标识相关资源并可用于检索、更新或删除它的东西。