资源不在 URL 中时的 REST API URL 结构
REST API URL structure when resource not in URL
我们正在创建两个 REST API
- 做模板处理
- 将 HTML 转换为 PDF。
1 中的模板和 2 中的 HTML 可以与请求正文一起提供，也可以存在于持久位置。
设计 REST 合约的最佳方式是什么？这些是设计它的好方法吗？或者对此有更好的建议吗？
对于场景 1
PUT - /template/process；在正文中包含模板标记PUT - /templates/{id}/process;在固定位置 {id}
对于场景 2
PUT /html2pdf/convert 正文中提到的 HTML 标记 PUT html2pdf/{id}/convert，资源 HTML，{id} 在永久位置可用。
在 URL 中也执行此操作（在本例中为 process、convert）是否是个好主意？或者是否可以使用 HTTP 动词本身为其赋予含义？
PUT 的使用是可疑的。请记住，REST 的部分要点是我们有一个统一的接口——每个人都以相同的方式理解 HTTP 消息。
特别是，PUT 是我们将网页上传到服务器时使用的方法令牌。请求的语义类似于“保存”或“更新插入”——您告诉服务器您想让服务器的目标资源副本看起来像您的目标资源副本。
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009
在很多与您的情况类似的情况下，我们想要的是 effectively read only request with a payload. As of early 2021, the registry of HTTP methods 不适合这种情况 - 最接近的选项是 SEARCH 和 REPORT，但这两个都带有 WebDAV 包袱。
但是在 2020 年底，HTTP WG 通过了 draft-snell-search-method 规范：
the scope of work is to define a method that has the behavior of a GET with a body -- Tommy Pauly
所以当这项工作完成后，我们将有另一种标准方法来考虑解决此类问题。
Is it a good idea to have the action too in the URL?
这是一个中立的想法。
URL/URI 是 标识符；它们（从协议的角度来看）在语义上是不透明的。只要你的拼写规则与RFC 3986中定义的产生式规则一致，你就可以随心所欲。
任何 HTTP 兼容组件都应该理解消息的语义是我的方法标记定义的，而不是由目标 uri 定义的。
Resources是泛化文件。 URI 实际上是文档的“名称”。您可以为您的文档使用任何对您的人有意义的名称（查看访问日志的操作员、尝试记录您的应用程序的技术作家、尝试阅读这些文档的其他开发人员等）。
我们正在创建两个 REST API
- 做模板处理
- 将 HTML 转换为 PDF。
1 中的模板和 2 中的 HTML 可以与请求正文一起提供，也可以存在于持久位置。
设计 REST 合约的最佳方式是什么？这些是设计它的好方法吗？或者对此有更好的建议吗？
对于场景 1
PUT - /template/process；在正文中包含模板标记PUT - /templates/{id}/process;在固定位置 中有一个模板
{id}
对于场景 2
PUT /html2pdf/convert正文中提到的 HTML 标记PUT html2pdf/{id}/convert，资源 HTML，{id}在永久位置可用。
在 URL 中也执行此操作（在本例中为 process、convert）是否是个好主意？或者是否可以使用 HTTP 动词本身为其赋予含义？
PUT 的使用是可疑的。请记住，REST 的部分要点是我们有一个统一的接口——每个人都以相同的方式理解 HTTP 消息。
特别是，PUT 是我们将网页上传到服务器时使用的方法令牌。请求的语义类似于“保存”或“更新插入”——您告诉服务器您想让服务器的目标资源副本看起来像您的目标资源副本。
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009
在很多与您的情况类似的情况下，我们想要的是 effectively read only request with a payload. As of early 2021, the registry of HTTP methods 不适合这种情况 - 最接近的选项是 SEARCH 和 REPORT，但这两个都带有 WebDAV 包袱。
但是在 2020 年底，HTTP WG 通过了 draft-snell-search-method 规范：
the scope of work is to define a method that has the behavior of a GET with a body -- Tommy Pauly
所以当这项工作完成后，我们将有另一种标准方法来考虑解决此类问题。
Is it a good idea to have the action too in the URL?
这是一个中立的想法。
URL/URI 是 标识符；它们（从协议的角度来看）在语义上是不透明的。只要你的拼写规则与RFC 3986中定义的产生式规则一致，你就可以随心所欲。
任何 HTTP 兼容组件都应该理解消息的语义是我的方法标记定义的，而不是由目标 uri 定义的。
Resources是泛化文件。 URI 实际上是文档的“名称”。您可以为您的文档使用任何对您的人有意义的名称（查看访问日志的操作员、尝试记录您的应用程序的技术作家、尝试阅读这些文档的其他开发人员等）。