时间戳

首页 > 解决方案 > 资源不在 URL 中时的 REST API URL 结构

rest - 资源不在 URL 中时的 REST API URL 结构

问题描述

我们正在创建两个 REST API

  1. 做一个模板处理
  2. 将 HTML 转换为 PDF。

1 中的模板和 2 中的 HTML 可以与请求正文一起提供，也可以存在于持久位置中。

设计 REST 合约的最佳方式是什么？这些是设计它的好方法吗？或者对此有更好的建议吗？

对于场景 1

  1. PUT - /template/process; 在正文中包含模板标记
  2. PUT - /templates/{id}/process; {id}在持久位置中有一个模板

对于场景 2

  1. PUT /html2pdf/convert带有正文中提到的 HTML 标记
  2. PUT html2pdf/{id}/convert与资源 HTML 一起{id}在持久位置中可用。

process在 URL 中也包含操作（convert在本例中为 ）是一个好主意吗？或者是否可以使用 HTTP 动词本身来赋予它含义？

标签： restapi-design

解决方案

PUT的使用是可疑的。请记住，REST 的部分意义在于我们有一个统一的接口——每个人都以同样的方式理解 HTTP 消息。

特别是，如果我们将网页上传到服务器，PUT 是我们使用的方法令牌。请求的语义类似于“save”或“upsert”——你告诉服务器你想让服务器的目标资源副本看起来像你的目标资源副本。

POST 在 HTTP 中有许多有用的用途，包括“此操作不值得标准化”的一般用途。——菲尔丁，2009

在许多与您类似的情况下，我们想要的是带有有效负载的有效只读请求。截至 2021 年初，HTTP 方法的注册表不适合这种情况 - 最接近的选项是 SEARCH 和 REPORT，但它们都带有 WebDAV 包袱。

但在 2020 年末，HTTP WG 采用了draft-snell-search-method规范：

工作范围是定义一种方法，该方法具有带有主体的 GET 行为——Tommy Pauly

所以当这项工作完成后，我们将有另一种标准方法来考虑这种类型的问题。

在 URL 中也包含操作是否是个好主意？

这是一个中立的想法。

URL/URI 是标识符；它们（从协议的角度来看）在语义上是不透明的。只要您的拼写约定与RFC 3986中定义的生产规则一致，您就可以随心所欲。

任何符合 HTTP 的组件都应该理解消息的语义是由方法令牌定义的，而不是由 target-uri 定义的。

资源是文档的概括。URI 实际上是文档的“名称”。您可以为您的文档使用任何对您的人有意义的名称（查看访问日志的操作员、尝试记录您的应用程序的技术作家、尝试阅读这些文档的其他开发人员等）。

推荐阅读