From 39c39ae4e0b04c797c043c3fed7bb3334775ae19 Mon Sep 17 00:00:00 2001 From: Greg Dubicki Date: Mon, 9 Mar 2020 20:29:15 +0100 Subject: [PATCH] Make the `data` vs `json` parameters more clear 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 ca95a0208b..636266cb47 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -279,8 +279,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'} @@ -289,8 +293,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 -----------------------------