REST API和UI网页的URI模式的最佳实践

Question

在Web编程缺席多年之后，我现在开始从头开始编写新的Web应用程序。 我了解了REST的知识，并找到了一些有关“ URI样式”的好坏的演讲和网络研讨会。 但是所有这些教程似乎都假定只有资源可以映射到持久存在于数据库中的实体。 如果需要GET某些内容的HTML（用户友好）版本，那么普遍的答案是通过HTTP标头字段使用内容否定。 最终目标似乎只有遵循REST范式的URI。

但是，显示无法映射到实体但仍然需要的网页的“正确”方式是什么？

也许我举一个例子来阐明我的意思。 假设我们有一个集合Persons和实体Person 。

那我们有

• POST /Persons/在集合中创建一个新人
• DELETE /Person/{id}/删除此人
• PUT /Person/{id}/修改此人（是的，我知道这也意味着创建一个人）
• GET /Persons/获取所有人员的列表
• GET /Person/{id}/以获取个人
• 等等

关于GET操作，我通常发现建议使用X-Requested-With的Accept和X-Requested-With标头字段来创建响应，该响应以计算机可读表示形式（即JSON，XML）返回“裸”人对象等等），或者返回完整的浏览器网页。

但是， PUT操作又如何呢？ 最终，此操作将发送将要创建的裸对象（即JSON，XLM），但是在此步骤之前，我需要从用户那里收集数据。 这意味着我需要一些空的Web表单，对于人类用户来说只是“眼睛糖果”。 当然，我可以使用GET /newPersonForm/类的东西，但这似乎与REST原理相矛盾，因为/newPersonForm/是仅指向某些用户界面元素的URI。

目前，我可以看到以下选项：

1. 两种URI使用相同的名称空间：

   • POST /Persons/ -> REST API
   • DELETE /Person/{id}/ -> REST API
   • PUT /Persons/{id}/ -> REST API
   • GET /Persons/ -> REST api或UI（内容否定后）
   • GET /Person/{id}/ -> REST api或UI（在内容否定之后）
   • GET /Person/creationForm >非REST纯UI
   • GET /aboutus >非REST，纯UI，其他公司信息

2. 单独命名空间：

   • /api/... >包含REST的所有内容
   • /ui/... >包含html网页

使用第一种方法，我觉得它有些“不干净”。 尽管第二种方法看起来更干净，但我看到了两个问题。 首先，如果一个人完全遵循这种方法，一个人将获得双倍的URI，因为一个人无需进行内容协商，并且为每个REST功能拥有一个UI网页。 我使用GET /api/Person/{id}/返回JSON对象，使用GET /ui/Person/{id}返回浏览器版本。 其次，我认为这种方法与REST原理背道而驰，因为搜索引擎和Web爬网程序无法理解站点的结构。

有什么建议是最佳实践吗？

Answer 1

首先，让我们摆脱一些误解。

1. 您可以通过URI识别语义的任何内容都是资源。

2. HTTP方法不会像这样映射到CRUD操作。 阅读此答案以获取更多信息。 我建议您先阅读它，然后再继续阅读此答案。 这可能也会有所帮助。

3. 没有遵循REST范式的URI之类的东西。 REST对URI施加的唯一限制是它们必须标识一个且只有一个资源，并且必须将它们视为原子标识符。 URI的语义无关紧要，尽管显然您应该设计对开发人员和用户有意义的URI。

正如您已经知道的那样，返回某些内容的用户友好表示形式的正确方法是通过使用Accept标头进行协商。 是否不是映射到数据库的对象也没关系。 这是只有服务器知道的实现细节，这就是REST的意义所在。 当您从REST API检索内容时，它是否来自应用程序服务器，某个地方的缓存，Amazon S3提供的静态文件甚至FTP链接都没有关系。 客户应该简单地跟随链接，例如单击网页上的链接，而不在乎结果从何而来。

您提供的两个选项均有效，但这与REST无关。 用api和ui分隔它们是为您组织事物的一种好方法，但是REST真正重要的是客户端如何获取这些链接。 如果他们通过阅读文档中的那些URI并填充值来实现客户端，那不是REST。

从网络浏览的角度考虑它。 您如何到达/newPersonForm html页面？ 您在其他地方跟踪了一个链接，该链接带有标签，告诉您单击它以创建一个新的Person。 如果您单击一下，则是/newPersonForm或/forms/newperson还是只是/persons /forms/newperson 。 REST的工作方式完全相同。