RESTful API设计-命名“活动”资源

Question

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

语义会更多：

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

要么

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

Answer 1

没有一个通用的答案，特别是因为在另一端执行查找/检索的机制以及相关的后端发生了巨大变化，更不用说用例用途和预期的应用程序了。

就是说，假设出于所有意图和目的，“模​​式”（或从最终用户的角度来看……端点约定）将保持不变，我已经看到了更多的后者活动约定，因为是实际资源，这是许多应用程序和API所围绕的资源。

我已经期望今天的API具有以下表示形式（它们如何实现引用和映射是另一回事，但从API参考的角度来看）-

{
    "Activity": [
        {
        "date": "1970-01-01 08:00:00",
        "some_other_resource_reference_uuid": "f1c4a41e-1639-4e35-ba98-e7b169d1c92d",
        "user": "b3ababc4-461b-404a-a1a2-83b4ca8c097f",
        "uuid": "0ccf1b41-aecf-45f9-a963-178128096c97"
        }
    ],
    "Users": [
        {
        "email": "johnanderson@mycompany.net",
        "first": "John",
        "last": "Anderson",
        "user_preference_1": "somevalue",
        "user_property_1": "somevalue",
        "uuid": "b3ababc4-461b-404a-a1a2-83b4ca8c097f"
        }
    ]
}

---

StackExchange API还允许通过多种方法检索对象：

例如， 用户类型如下：-

{
    "view_count": 1000,
    "user_type": "registered",
    "user_id": 9999,
    "link": "http://example.stackexchange.com/users/1/example-user",
    "profile_image": "https://www.gravatar.com/avatar/a007be5a61f6aa8f3e85ae2fc18dd66e?d=identicon&r=PG",
    "display_name": "Example User"
}

在“ 问题”类型上，同一用户显示在所有者对象下方：-

{
    "owner": {
        "user_id": 9999,
        "user_type": "registered",
        "profile_image": "https://www.gravatar.com/avatar/a007be5a61f6aa8f3e85ae2fc18dd66e?d=identicon&r=PG",
        "display_name": "Example User",
        "link": "https://example.stackexchange.com/users/1/example-user"
    },
    "is_answered": false,
    "view_count": 31415,
    "favorite_count": 1,
    "down_vote_count": 2,
    "up_vote_count": 3,
    "answer_count": 0,
    "score": 1,
    "last_activity_date": 1494871135,
    "creation_date": 1494827935,
    "last_edit_date": 1494896335,
    "question_id": 1234,
    "link": "https://example.stackexchange.com/questions/1234/an-example-post-title",
    "title": "An example post title",
    "body": "An example post body"
}

---

在帖子类型参考中（将其用作一个单独的示例，因为只有很少的方法可以达到该类型），您将在底部看到一个示例：

返回此类型的方法

帖子
帖子/ {ids}
用户/ {ids} /帖子 2.2
我/职位 2.2

因此，尽管您可以通过多种方式（包括过滤器和复杂的查询 ）访问资源（或“类型”，如StackExchange上的资源），但仍然存在通过许多更直接的透明URI约定查看所需资源的能力。

---

不同的应用程序显然会有不同的要求。 例如， Gmail API始终都是基于用户的 -从用户的角度来看，这是有道理的，因为在经过身份验证的凭据的上下文中，您要将一个用户对象与另一个用户对象分开。

这并不意味着Google对其所有API使用相同的约定，它们的Activity API资源全部与活动有关

即使查看Twitter API ，也存在Direct Messages端点资源，其中包含发送者和接收者对象。

我完全没有看到很多API仅限于仅通过用户端点访问资源，除非情况显然需要这样做，即上面的Gmail示例。

不管REST API有多灵活，我所期望的最低要求是某种Activity ，位置，物理对象或其他实体通常是其自己的资源，并且在不同程度上插入并引用了用户关联。灵活性（至少，本文顶部给出的示例）。

Answer 2

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

客户端应该只发现那些url，并且如果您最终决定要使用其他url结构，也应该适应新情况。

话虽这么说，对这种类型的东西有一个逻辑结构真是太好了。 但是，两者都可以。 您要征求意见，实际上没有标准或最佳实践。 也就是说，我将选择选项＃1。