REST API 中下载的正确 http 动词是什么? [英] What is the correct http verb for a Download in a REST API?

问题描述

我遇到过这样的情况，我不确定端点应该回答 POST 请求还是 GET 请求.

I have encountered a the case where I'm not sure whether an Endpoint should be answering a POST or a GET Request.

情况:

我有一个名为 Reports 的数据库表，以 UUID 作为主键.用户应该能够根据存储在不同表中的一些逻辑和数据，将报告创建为PDF.

I have a database table called Reports with UUIDs as primary keys. The user should be able to create a Report as PDF according to some logic and data stored in different tables.

现在，我将端点实现为 reports//export，这是一个 GET 端点.

For now I implemented an endpoint as reports/<uuid>/export which is a GET endpoint.

但是，在实现这一点之后，我很好奇:GET 甚至是该端点的正确 HTTP 动词/请求类型吗?

But, after implementing this, i was curious: Is GET even the correct HTTP verb/request type for this endpoint?

或者更一般的:提供主键下载资源的端点的正确 HTTP 动词是什么?

Or more general: What is the correct HTTP verb for an endpoint which provides a download of a resource provided a primary key?

推荐答案

提供主键下载资源的端点的正确 HTTP 动词是什么?

What is the correct HTTP verb for an endpoint which provides a download of a resource provided a primary key?

简短的回答是 GET 语义通常是您想要使用的.

Short answer is that GET semantics are normally what you want to use.

请求方法令牌是请求语义的主要来源；它指示客户端发出此请求的目的以及客户端期望的成功结果.RFC-7231；第 4.1 节

The request method token is the primary source of request semantics; it indicates the purpose for which the client has made this request and what is expected by the client as a successful result. RFC-7231; section 4.1

GET 方法请求传输目标资源的当前选定表示.GET 是信息检索的主要机制，也是几乎所有性能优化的重点.因此，当人们谈到通过 HTTP 检索某些可识别信息时，他们通常指的是发出 GET 请求.RFC-7231；第 4.3.1 节

The GET method requests transfer of a current selected representation for the target resource. GET is the primary mechanism of information retrieval and the focus of almost all performance optimizations. Hence, when people speak of retrieving some identifiable information via HTTP, they are generally referring to making a GET request. RFC-7231; section 4.3.1

资源由它们的 URI 标识；以下两个请求针对不同资源:

Resources are identified by their URI; the two requests below target different resources:

GET /example?uuid=764baee2-c5be-49cc-ac83-c9d1ea61d68a HTTP/1.1
GET /example?uuid=3b90b949-911c-433c-bec4-e6063f5377e0 HTTP/1.1

从 REST 的角度来看，尽管底层实现(也称为端点")可能相同，但它们是不同的.

From the point of view of REST, these are different even though the underlying implementation (aka the "endpoint") is likely to be the same.

您可以将 URI 本身视为用于在文档存储中查找资源的键.

You can think of the URI itself as being a key used to look up a resource in a document store.

更常见的是，我们将使用某种形式的模板从目标 uri 中提取我们在服务器上访问数据所需的特定信息——例如，从查询部分提取 uuid 参数并将其用作主键.

It's more common that we will use some form of template to extract from the target uri the specific information that we need on the server to access the data -- for instance, extracting the uuid parameter out of the query part and using that as a primary key.

这是理想的设置:如果请求语义是有效只读，并且我们期望返回资源的表示(例如，PDF)，那么 GET 就是我们想要的方法.

That's the ideal setting: if the request semantics are effectively read-only, and we are expecting a representation of the resource (for example, a PDF) to be returned, then GET is the method we want.

有时情况并不理想:当我们需要请求正文中包含的信息来做正确的事情时就会出现这种情况.在 HTTP 中，GET 请求上的有效负载(消息正文)具有 没有定义的语义.因此，如果您需要在请求中包含正文，则 GET 超出范围，您可能会改用 POST.

Sometimes circumstances aren't ideal: this comes about when we need information contained in the request-body to do the right thing. In HTTP, a payload (message-body) on a GET request has no defined semantics. So if you need to have a body on the request, then GET is out of bounds, and you are probably going to use POST instead.

在实践中发现了对请求行长度的各种特别限制.建议所有 HTTP 发送方和接收方至少支持 8000 个八位字节的请求行长度.RFC-7230；第 3.1.1 节

Various ad hoc limitations on request-line length are found in practice. It is RECOMMENDED that all HTTP senders and recipients support, at a minimum, request-line lengths of 8000 octets. RFC-7230; section 3.1.1

除非您控制客户端，否则您可能无法确保支持 8000 个八位字节.所以你通常会得到一个更简单的资源标识符，以及编码到消息正文中的大量信息(想想 SOAP 或 GraphQL), 和 POST 作为请求方法，因为其他方法的语义不适合.

Unless you control the clients, you may not be able to ensure that 8000 octets is supported. So you'll often instead end up with a simpler resource identifier, and lots of information encoded into the message-body (think SOAP, or GraphQL), and POST as the request method because the semantics of the other methods don't fit.

这并不理想，因为像资源的 PDF 表示应该是可缓存的，但是 HTTP 缓存的语义不支持请求的消息正文必须是缓存键的一部分的用例.请参阅 马克诺丁汉 2012-09-04

It's not ideal, because something like a PDF representation of a resource should be cacheable, but the semantics of HTTP caching don't support the use case where the request's message-body must be part of the cache key. See Mark Nottingham 2012-09-04

这篇关于REST API 中下载的正确 http 动词是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！