在 POST 上使用 URL 查询参数
Using URL Query Parameters on POST
我的团队需要构建一个 API 来上传文档，例如PDF。我的目标之一是让来电者尽可能轻松地完成这项工作。我相信使用作为流提供的二进制内容的 POST 调用是最直接的。一位团队成员指出，需要随本文档一起提供元数据。他假设这需要一个多部分 mime 请求。在我看来，这大大增加了服务用户的复杂性。
我建议在 URL 的 'query string' 中设置元数据。这允许元数据和文档的简单流解决方案。我们都相信从技术角度来看这应该可行，但他认为这是非标准的或可能不是 RESTful。
这对我来说似乎是一个非常简单的解决方案，但我确实找不到任何明确的答案来说明这是否有问题。我发现了一些似乎与此有关的讨论，但答案似乎都转向了 "mixing GET and POST"，我根本没有遵循。除非我遗漏了什么，否则这与 GET 无关，只是 POST 以及 POST 的 URL 的结构。似乎有人认为查询参数仅受 GET 支持，但我不认为是这样。
谁能提供权威的参考资料？
这取决于你所说的 "problematic" 是什么意思。从可用性的角度来看，它可能没有任何问题。请记住，REST 是一种架构 style，对样式的权威引用可能与样式本身一样主观。您可以找到关于您正在使用的传输协议 HTTP 的权威参考，但是何时偏离该协议会产生问题，而何时仅仅反对纯粹主义？阅读 RFC 7230 和 7231 并尝试找出答案。
换句话说，我是说，如果你在寻找权威来源来解决与同事的争论，我认为你不会找到它。
如果你只是想澄清一下，从REST的角度来看，URI是资源的原子标识符。查询参数是标识符的一部分，但由于它们是原子的，因此它们的语义无关紧要。这意味着任何关于 URI 是否为 RESTful 的讨论都是毫无意义的。只要 URI 指向一个且仅一个资源，并且它不是从带外信息中获取的，那么它就是 RESTful，无论其内容如何。当然，您应该尝试使用有意义且简单易懂的 URI，但这是 HTTP 上的一般最佳实践，而不是 REST 约束。
在您的案例中，真正的问题是 POST 方法的语义是根据预定义的规则提交要由 URI 标识的资源处理的有效负载。您在 POST 中使用的 URI 并不标识您正在上传的文件，而是负责上传的资源。如果您在 URI 中包含要处理的元数据，您实际上是在说每个 PDF 文件都是使用不同的上传资源上传的。从 REST 的角度来看，这在本质上没有错，但从 HTTP 和可用性的角度来看，这很奇怪。我希望每个人都使用相同的资源，并且有效载荷中会出现额外的数据。在这一点上，我认为您的同事是正确的，您应该使用多部分 mime 请求，或者允许您将 pdf 文件和元数据一起打包在有效负载中的媒体类型格式。
但是，如果您的元数据在上传 PDF 文件后没有改变——或者换句话说，如果您的 URI 没有改变——那么使用 PUT 方法就完全可以了。与POST方法不同的是，PUT不提交要由URI标识的资源处理的payload，而是要求服务器将URI处的资源替换为payload中包含的资源。在这种情况下，URI 确实标识了 PDF 文件，所以没关系，只要它不会改变。
我的团队需要构建一个 API 来上传文档，例如PDF。我的目标之一是让来电者尽可能轻松地完成这项工作。我相信使用作为流提供的二进制内容的 POST 调用是最直接的。一位团队成员指出，需要随本文档一起提供元数据。他假设这需要一个多部分 mime 请求。在我看来，这大大增加了服务用户的复杂性。
我建议在 URL 的 'query string' 中设置元数据。这允许元数据和文档的简单流解决方案。我们都相信从技术角度来看这应该可行，但他认为这是非标准的或可能不是 RESTful。
这对我来说似乎是一个非常简单的解决方案，但我确实找不到任何明确的答案来说明这是否有问题。我发现了一些似乎与此有关的讨论，但答案似乎都转向了 "mixing GET and POST"，我根本没有遵循。除非我遗漏了什么，否则这与 GET 无关，只是 POST 以及 POST 的 URL 的结构。似乎有人认为查询参数仅受 GET 支持，但我不认为是这样。
谁能提供权威的参考资料？
这取决于你所说的 "problematic" 是什么意思。从可用性的角度来看，它可能没有任何问题。请记住，REST 是一种架构 style，对样式的权威引用可能与样式本身一样主观。您可以找到关于您正在使用的传输协议 HTTP 的权威参考，但是何时偏离该协议会产生问题，而何时仅仅反对纯粹主义？阅读 RFC 7230 和 7231 并尝试找出答案。
换句话说，我是说，如果你在寻找权威来源来解决与同事的争论，我认为你不会找到它。
如果你只是想澄清一下，从REST的角度来看，URI是资源的原子标识符。查询参数是标识符的一部分，但由于它们是原子的，因此它们的语义无关紧要。这意味着任何关于 URI 是否为 RESTful 的讨论都是毫无意义的。只要 URI 指向一个且仅一个资源，并且它不是从带外信息中获取的，那么它就是 RESTful，无论其内容如何。当然，您应该尝试使用有意义且简单易懂的 URI，但这是 HTTP 上的一般最佳实践，而不是 REST 约束。
在您的案例中，真正的问题是 POST 方法的语义是根据预定义的规则提交要由 URI 标识的资源处理的有效负载。您在 POST 中使用的 URI 并不标识您正在上传的文件，而是负责上传的资源。如果您在 URI 中包含要处理的元数据，您实际上是在说每个 PDF 文件都是使用不同的上传资源上传的。从 REST 的角度来看，这在本质上没有错，但从 HTTP 和可用性的角度来看，这很奇怪。我希望每个人都使用相同的资源，并且有效载荷中会出现额外的数据。在这一点上，我认为您的同事是正确的，您应该使用多部分 mime 请求，或者允许您将 pdf 文件和元数据一起打包在有效负载中的媒体类型格式。
但是，如果您的元数据在上传 PDF 文件后没有改变——或者换句话说，如果您的 URI 没有改变——那么使用 PUT 方法就完全可以了。与POST方法不同的是，PUT不提交要由URI标识的资源处理的payload，而是要求服务器将URI处的资源替换为payload中包含的资源。在这种情况下，URI 确实标识了 PDF 文件，所以没关系，只要它不会改变。