时间戳

首页 > 解决方案 > RESTful API - 资源的自定义表示

rest - RESTful API - 资源的自定义表示

问题描述

例子

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

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

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

问题

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

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

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

标签： resthttprestful-url

解决方案

这种代表选择应该如何表达？

有权衡。

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

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

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

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

另一种可能性是将其视为具有多种表示形式的单个资源（一个标识符）。我们通过内容协商来做到这一点

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

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

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

从 2006 年开始回顾这个线程可能会有所帮助，特别是 Roy Fielding 关于为不同语言使用单独的 uri 树的观察。

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

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

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

推荐阅读