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

这不是一个通用的答案，特别是因为在另一端进行查找/检索的机制以及相关的后端变化如此剧烈，更不用说用例目的和预期的应用程序了。 / p>

那说，假设所有的意图和目的＆＃34;架构＆＃34; （或者......从最终用户的角度来看端点约定）只是平坦的，我已经看到了更多的后者活动约定，因为那是实际的资源，是许多应用程序和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允许通过多种方法检索对象：

例如， User 类型如下所示： -

{
    "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"
}

在 Question 类型上，同一位用户显示在所有者对象下方： -

{
    "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"
}

在Posts Type引用（将此作为单独的示例使用，因为只有少数方法可以达到此类型），您将在底部看到一个示例：

返回此类型的方法

posts
posts/{ids}
users/{ids}/posts 2.2
me/posts 2.2

因此，虽然您可以通过包括filters和complex queries在内的多种方式访问资源（或＃34;类型＆＃34;就像在StackExchange上一样），但仍然存在通过一些更直接的透明URI约定来查看所需的资源。

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

这并不意味着谷歌对所有API使用相同的约定，他们的Activities API资源都是关于活动

即使查看Twitter API，也有一个Direct Messages端点资源，其中包含发件人和收件人对象。

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

无论REST API的灵活性如何，我所期望的最低限度是某种活动，位置，物理对象或其他实体通常是它自己的资源，并以不同程度的灵活性插入和引用用户关联（至少，本文顶部给出的示例）。

Answer 2

应该指出的是，在真正的REST api中，uri没有任何意义。这是您的组织和用户资源之间的链接关系。

客户应该发现这些网址，如果你决定想要一个不同的网址结构，也应该适应新的情况。

话虽如此，拥有这种类型的逻辑结构是件好事。但是，要么是好的。你要求的意见，没有真正的标准或最佳实践。也就是说，我会选择＃1选项。

RESTful API设计 - 命名＆＃34;活动＆＃34;资源

2 个答案: