RESTful API - 资源的自定义表示答案

【问题标题】：RESTful API - Custom representation of a resourceRESTful API - 资源的自定义表示
【发布时间】：2020-11-19 07:45:28
【问题描述】：

示例

有一个系统可以让人们提交休假，数据的结构如下：

LeaveOfAbsence {
   reason: string;   
   from: string; // ISO8601 date string
   to: string; // ISO8601 date string
}

现在，当客户端请求资源时，它会在给定的时间范围内请求提交的项目，并希望数据采用以下格式之一：

问题

在这种情况下，似乎请求的资源是相同的，在给定的时间段内提交的项目，但它的表示不同：原始格式与视图友好格式。

应该如何表达这种选择？我在想一个查询字符串（例如spread=true）可以工作，但也许有不同/更好的方法？（自定义标题？）

（如果我对 RESTful API 的理解有误，请告诉我。）

【问题讨论】：

【解决方案1】：

这种表示方式的选择应该如何表达？

需要权衡取舍。

如果你查看resource的定义，你应该可以看到“友好格式的信息”和“非友好格式的信息”可以是两个不同的资源，具有不同的标识符。

http://example.org/html/interesting-report
http://example.org/json/interesting-report

但是，当您这样做时，通用组件（浏览器、缓存等）将假定这两个标识符是不相关的（就像它们都与 http://example.org/html/unrelated-report 无关一样）。

这意味着，当我们发送的请求导致其中一个文档从缓存中失效时——缓存不会神奇地知道也会使另一个文档失效。

另一种可能性是将其视为具有多种表示形式的单个资源（一个标识符）。我们通过content negotiation 进行此操作

最常见的形式是proactive negotiation，服务器根据请求中包含的metadata 选择适当的表示形式发送。您可能会在 Web 浏览器中看到：当浏览器获取图像数据时，它可能包含一个 Accept 标头，描述浏览器本身支持的不同图像媒体类型的偏好。

当服务器在响应中包含Vary 标头时，通用缓存可以区分哪些请求应该接收先前缓存的资源表示，而哪些应该被传递给服务器以获得新的表示相同的资源。

因为所有表示共享相同的公共标识符，所以它们都服从相同的cache invalidation 语义。因此，向资源发送成功的 POST 会使所有的缓存表示无效。

查看此thread from 2006 可能会有所帮助，尤其是 Roy Fielding 关于为不同语言使用单独 uri 树的观察。

像往常一样，标识符的拼写与机器无关，除非是非常笼统的术语（例如，我们可以将dot segments 用于路径段，但不能用于查询部分）。

/html/interesting-report
/interesting-report.html
/interesting-report?html
/interesting-report?format=html

这些都很好——absolute URI 标识了文档，并且通用组件不会尝试从标识符中提取资源语义。拼写的选择往往受到其他问题的驱动（我们是否要支持点段？我们容易实现什么？操作员在日志中容易识别什么，等等）。

【讨论】：