我应该如何处理 RESTful API 中的对象层次结构？

Question

我目前正在为现有 PHP 应用程序设计 API，为此正在研究 REST 作为一种明智的架构方法。

我相信我对关键概念有了合理的掌握，但我正在努力寻找任何解决过对象层次结构和 REST 问题的人。

问题是......

在[应用程序]业务对象层次结构中，我们有：

Users 
 L which have one-to-many Channel objects
 L which have one-to-many Member objects
 

在应用程序本身中，我们使用延迟加载方法根据需要使用这些对象的数组填充用户对象。我相信从面向对象的角度来看，这是对象聚合，但我已经看到了各种命名不一致的情况，并且不关心引发一场关于精确命名约定的战争。

现在，考虑一下我有一些松散耦合的对象，根据应用程序的需要，我可能/可能不会填充这些对象。

从 REST 的角度来看，我试图确定该方法应该是什么。这是我目前的想法（暂时只考虑 GET）：

选项 1 - 完全填充对象：

GET api.example.com/user/{user_id}

读取 User 对象（资源）并返回 User 对象以及所有可能的 Channel 和 Member 对象- 加载并编码（JSON 或 XML）。

优点：减少对象数量，无需遍历对象层次结构
缺点：必须完全填充对象（昂贵）

选项 2 - 填充主对象并包含指向其他对象资源的链接：

GET api.example.com/user/{user_id}

读取用户对象（资源）并返回填充的用户对象用户数据和两个列表。

每个列表都引用适当的（子）资源，即

api.example.com/channel/{channel_id}
api.example.com/member/{member_id}
    

我认为这接近（或完全）超媒体的含义 - 客户端可以根据需要获取其他资源（只要我明智地标记它们）。

优点：客户端可以选择加载从属或其他方式，更好地将对象分离为 REST 资源
缺点：需要进一步访问才能获取辅助资源

选项 3 - 启用递归检索

GET api.example.com/user/{user_id}

读取 User 对象并包含指向子对象列表的链接，即

api.example.com/user/{user_id}/channels
api.example.com/user/{user_id}/members

/channels 调用将返回以下通道资源列表形式（如上）：

api.example.com/channel/{channel_id}
    

优点：主要资源公开去哪里获取下属，但不公开它们是什么（更 RESTful？），不需要预先获取下属，下属列表生成器（/channels 和 /members）提供接口（类似方法），使响应更像服务。
缺点：现在需要三个调用才能完全填充对象

选项 4 - （重新）考虑 REST 的对象设计

我正在重新使用[现有]应用程序对象层次结构并尝试将其应用于 REST -或者更直接地，为它提供一个API接口。

也许 REST 对象层次结构应该有所不同，或者新的 RESTful 思维可能暴露了现有对象设计的局限性。

欢迎对上述任何想法。

Answer 1

没有理由不将这些结合起来。

• api.example.com/user/{user_id} – 返回用户表示
• api.example.com/channel/{channel_id} – 返回渠道表示
• api .example.com/user/{user_id}/channels – 返回频道表示列表
• api.example.com/user/{user_id}/channel_list – 返回频道 ID 列表（或使用上述链接链接到其完整表示）

如有疑问，请考虑如何向人类用户显示数据而无需考虑“API”：用户需要两个索引页面 ({user_id}/channel_list）和完整视图（{user_id}/channels）。

一旦你有了这个，只需支持 JSON 而不是（或除了）HTML 作为表示格式，你就拥有了 REST。

Answer 2

我能给出的最好建议是尽量避免将 REST api 视为公开对象。您创建的资源应该支持您需要的用例。如果有必要，您可以为所有三个选项创建资源：

api.example.com/completeuser/{id}
api.example.com/linkeduser/{id}
api.example.com/lightweightuser/{id}

显然我的名字有点愚蠢，但您叫它们什么并不重要。这个想法是，您使用 REST api 以最符合特定使用场景的逻辑方式呈现数据。如果有多个场景，请根据需要创建多个资源。我喜欢将我的资源视为 UI 模型而不是业务实体。

Answer 3

我会推荐Restful Obects，它是暴露领域模型的restful的标准

Restful Objects的想法是提供一个标准的、通用的RESTful接口对于域对象模型，使用 JSON 公开其结构的表示，并使用 HTTP GET、POST、PUT 和 DELETE 实现与域对象实例的交互。

根据标准，URI 将类似于：

• api.example.com/object/user/31
• api.example.com/object/user/31/properties/username
• api.example.com/object/user/31/collections /channels
• api.example.com/object/user/31/collections/members
• api.example.com/object/user/31/actions/someFunction
• api.example.com/object/user/31/actions/someFunction/invoke

有也是其他资源

• api.example.com/services
• api.example.com/domain-types

该规范定义了一些主要表示形式：

• 对象（表示任何域对象或服务）
• 列表（指向其他对象的链接）
• 属性
• 收集
• 操作
• 操作结果（通常包含对象或列表，或仅包含反馈消息）
• 以及少量辅助表示，例如家庭和用户

这很有趣，因为您会看到表示是完全自描述的，从而开启了可能性如果需要，将实施通用查看器。

或者，这些表示可以直接由定制应用程序使用。

Answer 4

以下是我经过数小时的搜索和响应者的输入得出的结论：

如果我有一个实际上是多部分对象的对象，我需要将其视为单个资源。因此，如果我获取该对象，则所有下属都应该在场。为了使资源可缓存，这是必需的。如果我部分加载对象（并提供 ETag 标记），那么其他请求者可能会在期望完整对象时收到部分对象。 结论 - 如果对象可作为资源使用，则应完全填充对象。

关联的对象关系应作为指向其他（主要）资源的链接提供。通过这种方式，可以通过遍历 API 来发现对象。

此外，对主应用程序站点有意义的对象层次结构可能看起来不是您以 RESTful 方式操作所需的内容，但更有可能揭示问题与现有的层次结构。话虽如此，API 可能需要比之前设想的更专门的用例，并且可能需要专门的资源。

希望对某人有帮助