对此没有一个通用的答案,特别是因为在另一端进行查找/检索的机制以及相关的后端变化如此之大,更不用说用例目的和预期的应用程序了。
也就是说,假设出于所有意图和目的,“模式”(或......从最终用户的角度来看的端点约定)只是平坦的,我已经看到了更多后者 activity 约定,因为它是实际资源,许多应用程序和 API 都是围绕它开发的。
今天我已经开始期待 API 的以下表示风格(它们如何实现引用和映射是另一回事,但从 API 引用的角度来看)
-
{
“活动”: [
{
“日期”:“1970-01-01 08:00:00”,
“some_other_resource_reference_uuid”:“f1c4a41e-1639-4e35-ba98-e7b169d1c92d”,
“用户”:“b3ababc4-461b-404a-a1a2-83b4ca8c097f”,
“uuid”:“0ccf1b41-aecf-45f9-a963-178128096c97”
}
],
“用户”:[
{
“电子邮件”:“johnanderson@mycompany.net”,
“第一”:“约翰”,
“最后”:“安德森”,
“user_preference_1”:“某个值”,
“user_property_1”:“某个值”,
“uuid”:“b3ababc4-461b-404a-a1a2-83b4ca8c097f”
}
]
}
StackExchange API 还允许通过多种方法检索对象:
例如,User 类型如下所示:
-
{
“view_count”:1000,
"user_type": "已注册",
"user_id": 9999,
"链接": "
http://example.stackexchange.com/users/1/example-user",
"profile_image": "
https://www.gravatar.com/avatar/a007be5a61f6aa8f3e85ae2fc18dd66e?d=identicon&r=PG",
"display_name": "示例用户"
}
在 Question 类型上,同一用户显示在 owner 对象下方:
-
{
“所有者”: {
"user_id": 9999,
"user_type": "已注册",
"profile_image": "
https://www.gravatar.com/avatar/a007be5a61f6aa8f3e85ae2fc18dd66e?d=identicon&r=PG",
"display_name": "示例用户",
"链接": "
https://example.stackexchange.com/users/1/example-user"
},
“is_answered”:假,
“view_count”:31415,
"favorite_count": 1,
“down_vote_count”:2,
“up_vote_count”:3,
"answer_count": 0,
“分数”:1,
“last_activity_date”:1494871135,
“创作日期”:1494827935,
“last_edit_date”:1494896335,
“question_id”:1234,
"链接": "
https://example.stackexchange.com/questions/1234/an-example-post-title",
"title": "一个示例帖子标题",
"body": "一个示例帖子正文"
}
在Posts Type 参考(使用此作为单独的示例,因为只有少数方法可以达到此类型),您会在底部看到一个示例:
返回此类型的方法
posts
posts/{ids}
users/{ids}/posts 2.2
me/posts 2.2
因此,尽管您可以通过多种方式(包括 filters 和 complex queries)访问资源(或 StackExchange 上的“类型”),但仍然可以通过更多方式查看所需资源直接透明的 URI 约定。
不同的应用程序显然会有不同的要求。例如,Gmail API 一直是基于用户的 - 从用户的角度来看,这是有道理的,因为在经过身份验证的凭据的上下文中,您将一个用户对象与另一个用户对象分开。
这并不意味着 google 对其所有 API 使用相同的约定,他们的 Activities API 资源都是关于 activity
即使查看 Twitter API,也有一个 Direct Messages 端点资源,其中包含 sender 和 receiver 对象。
我还没有看到很多 API 仅限于纯粹通过 用户 端点访问资源,除非情况显然需要它,即 Gmail 示例以上。
不管 REST API 有多灵活,我所期望的最低限度是某种 Activity、位置、物理对象或其他实体通常是它自己的资源,并且用户关联以不同程度的灵活性插入和引用(至少,本文顶部给出的示例)。