From ab38e2c72608b95b047b05ccfaca833edb9db1b1 Mon Sep 17 00:00:00 2001 From: Greg Dubicki Date: Wed, 29 Dec 2021 18:46:21 +0100 Subject: [PATCH] Make the `data` vs `json` parameters more clear (#5382) As https://stackoverflow.com/q/26685248/2693875 question and answer popularity shows that there is a lot of people who do not understand the distinction. --- docs/user/quickstart.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 4e70af957c..bc0efc8939 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -283,8 +283,12 @@ For example, the GitHub API v3 accepts JSON-Encoded POST/PATCH data:: >>> r = requests.post(url, data=json.dumps(payload)) -Instead of encoding the ``dict`` yourself, you can also pass it directly using -the ``json`` parameter (added in version 2.4.2) and it will be encoded automatically:: +Please note that the above code will NOT add the ``Content-Type`` header +(so in particular it will NOT set it to ``application/json``). + +If you need that header set and you don't want to encode the ``dict`` yourself, +you can also pass it directly using the ``json`` parameter (added in version 2.4.2) +and it will be encoded automatically: >>> url = 'https://api.github.com/some/endpoint' >>> payload = {'some': 'data'} @@ -293,8 +297,6 @@ the ``json`` parameter (added in version 2.4.2) and it will be encoded automatic Note, the ``json`` parameter is ignored if either ``data`` or ``files`` is passed. -Using the ``json`` parameter in the request will change the ``Content-Type`` in the header to ``application/json``. - POST a Multipart-Encoded File -----------------------------