web-services - 社交网络的 RESTful 设计

Question

我正在尝试围绕 RESTful 设计进行思考，我想从社交网络的角度来理解它。我已阅读 REST API Design Rulebook ，查看了一些其他书籍并阅读了大量在线资源。尽管如此，当将规则应用于现实世界的问题时，我意识到我并没有完全理解一切。我想通过指定一些问题来了解我是否对 REST 有正确的理解:
层次结构与平面设计
让我们假设我用

/users/42

现在，该用户上传的照片最终会在

/users/42/photos

如果他/她在照片中标记他/她的 friend ，这些标记最终会出现在

/users/42/photos/1337/tags

但这无法找到标记特定用户的所有照片。我应该为此提出不同的层次结构吗？好像有点别扭。我是否可以完全无视层次结构并结合这样的查询提供照片？

/photos?owner=42
/photos?tagged=42

当不同用户的内容不同时缓存
Web 服务应该设计为提供可缓存的数据(以便客户端可以决定使用本地副本，如果它认为没有任何更改)，但这如何影响不同用户的隐私设置？两个都登录的用户可能有权查看不同的信息，例如用户 42. 这是否意味着我需要为访问同一用户的个人资料信息的不同用户请求不同的 URI，或者只要用户提供不同的凭据，缓存就不会成为问题？
从同一资源提供 HTML 和 JSON/XML
我提到的那本书指定了 API 应该可以在以 api 开头的子域中访问的规则。 ，在他们的例子中 http://api.soccer.restapi.org .我曾计划对用户访问和机器访问(例如移动应用程序)使用相同的 Controller 。 Controller 将通过 text/html 决定提供哪个 View ( application/json 、 application/xml 或 Accept ) HTTP 请求头中的字段。我认为出于某种原因这将是一个坏主意(因为用户希望看到子域 www ，而不是 api )，但我不明白为什么。可以 www和 api指向同一台服务器，还是我真的应该尝试将 HTML View 移动到不同的虚拟主机？为什么？
我相信 Ruby on Rails 将(Convention over Configuration)从同一个 Controller 提供 HTML 和 JSON，从而分享我的想法，即 HTML 和 JSON 只是相同数据的不同表示。
换句话说，我的书说某个资源应该只有一个 URI，并且应该根据 Accept 提供不同的表示形式。 field 。在不同的子域之间重定向用户将违反关于提供来自同一资源的任何表示的规则，并且复制信息(即，将两个子域指向同一虚拟主机)违反关于不为同一资源提供多个 URI 的规则。不提供 api子域违反了另一个设计规则。我怎样才能在不违反任何规则的情况下解决这个问题？
限制发回的数据
查询组件应该用于分页，但我是否可以在不违反 REST 的情况下拒绝满足缺乏搜索条件的列表请求并限制项目数量？我想既减少数据库负载又避免让某人映射整个用户目录。我想要

/users

是非法请求，而

/users?name=leet+hacker

将有效但仅返回例如100 项。
我还想知道仅在使用查询特别请求时才返回数据库列的子集和更多/所有列是否合法。
提供冗余数据的 Controller
我相信提供这样的 Controller 是合法的

/users/me

但它是否应该提供与文档 URI 完全相同的信息

/users/42

还是应该重定向到它？
某些用户的扩展权限
哪种 RESTful 方式可以提供附加功能，例如管理权限？我现在假设管理员(照片的、一组用户的或整个站点的)将能够比其他用户看到更多关于特定对象的信息。该信息是否应该保存在完全相同的 URI 并自动发送给管理员而不是其他任何人，是否应该存储在不同的位置，是否应该使用某个管理员查询来请求或以其他方式提供？
本地化和设置更新
尽管用户可见的大多数字符串应由 View 提供，但仍有一些设计决策可能涉及 API。最明显的是名字。社交网络有时允许用户输入将在不同语言上下文中显示的不同名称。某些语言(如俄语和阿拉伯语)中的姓名不容易自动转录。在其他语言中，例如中文，本地名称和国际名称可能完全不同，完全没有相似之处或联系。处理这个问题的 RESTful 方式是什么？我有一种感觉，答案将是 Accept-Language领域，但有没有人认真考虑过在他们所属的社交网络上切换语言？所有这些信息都应该每次都返回给调用者，还是我可以依赖设置？这可以与缓存一起使用吗？

Answer 1

正如@Mark Dickinson 提到的，这里有很多问题，确实应该分开讨论，但我会尽力而为。

层次结构与平面设计

REST 中没有任何内容表明您不能拥有多个并行层次结构(尽管我知道使用 Rails 这样做很尴尬)。有 /users/42/photos/owner和 /photos/owner/42包含相同的集合很好。同样/users/42/photos/tagged和 /photos/tagged/42可以包含相同的集合。但是，此时您不必担心 URI。有一篇优秀文章A RESTful Hypermedia API in Three Easy Steps描述了如何设计你的 API。在本文中，URI 被确定为最后一步。

另外，使用 HATEOAS限制条件下，客户端应在运行时通过应用程序提供的链接和表单发现这些不同的 URI。

不同用户的内容不同时缓存

如果您要从同一个 URL 提供不同的内容，那么它将无法缓存。您可以将您的站点划分为两种类型的内容，公开的和个性化的。公共(public)内容对每个人都应该相同，并且可以缓存。每个用户的个性化内容都不同，这意味着您可以缓存它的数量将大大减少(使用您在示例中使用的 URL 格式减少到零)。

要在个性化内容上至少获得少量缓存，请按用户对内容进行分区，这样对于给定用户，您将获得一些缓存命中。例如，代替 /users/42每个人都可以访问，使用 /<UID>/users/42哪里是请求用户的用户 ID。例如用户 234 将使用 URI /234/users/42 访问用户 42 的个人资料页面.对于匿名用户，您可以删除 /<UID部分或使用特定的用户 ID，例如 /public/users/42 .

从同一资源同时提供 HTML 和 JSON/XML

使用 Accept标题。这就是它的用途。

限制发回的数据

您不需要制作 /users非法请求。 Treat 是一个集合，并返回请求者可以查看的分页用户列表。例如，对于匿名请求，您可能会提供一个空列表(或 204 No Content)

<users/>

对于特定的登录用户，您可以提供他们的 friend 。

<users>
    <user id="42" href="/users/42" name="John Doe"/>
    <user id="53" href="/users/53" name="Jane Doe"/>
    ...
    <next href="/users?page=2"/>
</users>

当该用户然后获取 /users?page=2然后您将提供下一页结果

<users>
    <user id="69" href="/users/69" name="John Smo"/>
    <user id="84" href="/users/84" name="Jane Smo"/>
    ...
    <next href="/users?page=3"/>
    <prev href="/users"/>
</users>

结果的最后一页没有提供 next关联。要添加搜索功能，您只需添加一个适当的表单作为响应的一部分。

<users>
    <user id="69" href="/users/69" name="John Smo"/>
    <user id="84" href="/users/84" name="Jane Smo"/>
    ...
    <next href="/users?page=2"/>
    <prev href="/users"/>
    <search href="/users" method="get">
        <name cardinality="required" type="regex"/>
    </search>
</users>

搜索结果将被分页，就像 /users列表。例如，搜索 leet hacker (假设您有权查看系统中的许多 leet 黑客)会产生类似

<users>
    <user id="234" href="/users/234" name="leet hacker"/>
    <user id="999" href="/users/999" name="leet hacker"/>
    ...
    <next href="/users?name=leet+hacker&page=2"/>
    <search href="/users" method="get">
        <name cardinality="required" type="regex"/>
    </search>
</users>

但是，您可能需要在用户元素中提供更多详细信息，以便可以区分 leet 黑客。

提供冗余数据的 Controller

两者都可以接受。但是如上所述(出于缓存原因)我会使用 /<UID>/users/42 ，在这种情况下，您可能希望重定向 /42/users/me至 /42/users/42 .

从分析的角度来看，这也有帮助，因为您可能希望分别跟踪用户访问他们自己的页面，从用户访问其他用户页面，找出哪些用户受欢迎，哪些用户自恋。您甚至可能会发现两者之间存在相关性:)

部分用户的扩展权限

在适当的响应中提供管理链接和表单。例如，访问其他人图像的详细信息可能会提供

<image id="266" href="/photos/266" caption="leet hacker with computer"
       src="http://us.123rf.com/400wm/400/400/creatista/creatista0911/creatista091100003/5827629.jpg"/>
    <tagged-users>
        <user id="234" href="/users/234" name="leet hacker"/>
    </tagged-users>
    <owner id="234" href="/users/234" name="leet hacker"/>
</image>

但对于图像所有者，它可能会提供

<image id="266" href="/photos/266" caption="leet hacker with computer"
       src="http://us.123rf.com/400wm/400/400/creatista/creatista0911/creatista091100003/5827629.jpg"/>
    <tagged-users>
        <tagged-user id="234" href="/users/234" name="leet hacker">
            <delete href="/photos/266/tagged/234" method="delete"/> 
        </tagged-user>
        <add href="/photos/266" method="put">
            <user cardinality="required" type="user-id"/>
        </add>
    </tagged-users>
    <owner id="234" href="/users/234" name="leet hacker"/>
    <delete href="/photos/266" method="delete"/>
    <update href="/photos/266" method="put">
        <caption cardinality="optional" type="string"/>
    </update>
</image>

本地化和设置更新

使用 Accept-Language默认语言，但允许用户在其设置中更改语言。