【问题标题】:RESTful API design - naming an "activity" resourceRESTful API 设计 - 命名“活动”资源
【发布时间】:2017-05-16 03:29:12
【问题描述】:

在为activity 资源设计端点时,该资源提供有关其他资源(例如users 和organisations)的活动信息,我们正在努力使用命名约定。

什么更符合语义:

/organisations/activity
/organisations/activity/${activityId}
/users/activity
/users/activity/${activityId}

或

/activity/users/${activityId}
/activity/users
/activity/organisations/${activityId}
/activity/organisations

【问题讨论】:

    标签: node.js rest api http express


    【解决方案1】:

    对此没有一个通用的答案,特别是因为在另一端进行查找/检索的机制以及相关的后端变化如此之大,更不用说用例目的和预期的应用程序了。

    也就是说,假设出于所有意图和目的,“模​​式”(或......从最终用户的角度来看的端点约定)只是平坦的,我已经看到了更多后者 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、位置、物理对象或其他实体通常是它自己的资源,并且用户关联以不同程度的灵活性插入和引用(至少,本文顶部给出的示例)。

    【讨论】:

    • @AndrewMcLagan 点头。很抱歉缺乏支持信息。我一直在尝试编辑这个我得到的每一次机会......但是如果我每次“您的帖子似乎包含格式不正确的代码”出现时我都有一美元 - 哎呀跨度>
    【解决方案2】:

    应该指出,在真正的 REST api 中,uri 没有任何意义。重要的是来自组织和用户资源的链接关系。

    客户端应该只是发现这些 url,如果你决定想要一个不同的 url 结构,还应该适应新的情况。

    话虽如此,为这类事情有一个逻辑结构很好。但是,两者都可以。您是在征求意见,实际上并没有标准或最佳实践。也就是说,我会选择选项 #1。

    【讨论】:

      猜你喜欢
      • 1970-01-01
      • 1970-01-01
      • 1970-01-01
      • 2015-03-17
      • 1970-01-01
      • 1970-01-01
      • 1970-01-01
      • 2021-09-30
      • 2020-05-30
      相关资源
      最近更新 更多