json REST API 最佳实践：查询字符串中的参数与请求正文中的参数
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/25385559/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
REST API Best practices: args in query string vs in request body
提问by Jonathan
A REST API can have arguments in several places:
REST API 可以在几个地方有参数：
- In the request body- As part of a json body, or other MIME type
- In the query string- e.g.
/api/resource?p1=v1&p2=v2 - As part of the URL-path- e.g.
/api/resource/v1/v2
- 在请求正文中- 作为 json 正文或其他 MIME 类型的一部分
- 在查询字符串中- 例如
/api/resource?p1=v1&p2=v2 - 作为 URL 路径的一部分- 例如
/api/resource/v1/v2
What are the best practices and considerations of choosing between 1 and 2 above?
2 vs 3 is covered here.
回答by stan0
What are the best practices and considerations of choosing between 1 and 2 above?
在上述 1 和 2 之间进行选择的最佳做法和注意事项是什么？
Usually the content body is used for the data that is to be uploaded/downloaded to/from the server and the query parameters are used to specify the exact data requested. For example when you upload a file you specify the name, mime type, etc. in the body but when you fetch list of files you can use the query parameters to filter the list by some property of the files. In general, the query parameters are property of the query not the data.
通常，内容正文用于上传/下载到服务器/从服务器下载的数据，查询参数用于指定所请求的确切数据。例如，当您上传文件时，您在正文中指定名称、mime 类型等，但是当您获取文件列表时，您可以使用查询参数按文件的某些属性过滤列表。通常，查询参数是查询的属性而不是数据。
Of course this is not a strict rule - you can implement it in whatever way you find more appropriate/working for you.
当然，这不是一个严格的规则——你可以用任何你认为更合适/更适合你的方式来实现它。
You might also want to check the wikipedia article about query string, especially the first two paragraphs.
您可能还想查看有关 query string的维基百科文章，尤其是前两段。
回答by Leonel Galán
I'll assume you are talking about POST/PUT requests. Semantically the request body should contain the data you are posting or patching.
我假设您在谈论 POST/PUT 请求。从语义上讲，请求正文应包含您发布或修补的数据。
The query string, as part of the URL (a URI), it's there to identify which resource you are posting or patching.
查询字符串作为 URL（URI）的一部分，用于标识您要发布或修补的资源。
You asked for a best practices, following semantics are mine. Of course using your rules of thumb should work, specially if the web framework you use abstract this into parameters.
您要求最佳实践，以下语义是我的。当然，使用您的经验法则应该有效，特别是如果您使用的 Web 框架将其抽象为parameters。
You most know:
你最了解：
- Some web servers have limits on the length of the URI.
- You can send parameters inside the request body with CURL.
- Where you send the data shouldn't have effect on debugging.
- 某些 Web 服务器对 URI 的长度有限制。
- 您可以使用 CURL 在请求正文中发送参数。
- 发送数据的位置不应影响调试。
回答by Jonathan
The following are my rules of thumb...
以下是我的经验法则...
When to use the body:
何时使用身体：
- When the arguments don't have a flat key:value structure
- If the values are not human readable, such as serialized binary data
- When you have a very large number of arguments
- 当参数没有平面键：值结构时
- 如果值不是人类可读的，例如序列化的二进制数据
- 当您有大量参数时
When to use the query string:
何时使用查询字符串：
- When the arguments are such that you want to see them while debugging
- When you want to be able to call them manually while developing the code e.g. with
curl - When arguments are common across many web services
- When you're already sending a different content-type such as
application/octet-stream
- 当参数是这样的，你想在调试时看到它们
- 当您希望能够在开发代码时手动调用它们时，例如
curl - 当参数在许多 Web 服务中通用时
- 当您已经发送不同的内容类型时，例如
application/octet-stream
Notice you can mix and match - put the the common ones, the ones that should be debugable in the query string, and throw all the rest in the json.
请注意，您可以混合和匹配 - 将常见的、应该可调试的放在查询字符串中，并将所有其余的放在 json 中。
