From: Stephen Finucane <stephen@that.guru>
Date: Thu, 1 Jun 2017 13:48:22 +0000 (+0100)
Subject: docs: Detail JSON PATCH requests
X-Git-Tag: v2.2.0-rc1~166
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2782fcfd581bd32e050c9237de29f00cd5d7a89e;p=thirdparty%2Fpatchwork.git

docs: Detail JSON PATCH requests

It turns out it is possible to make PATCH requests with JSON bodies
rather than form-encoded data - you just need to include a Content-Type
header. Document this.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---

diff --git a/docs/api/rest.rst b/docs/api/rest.rst
index ea43095c..6b11ac77 100644
--- a/docs/api/rest.rst
+++ b/docs/api/rest.rst
@@ -160,13 +160,28 @@ string parameters:
     $ curl 'https://patchwork.example.com/api/patches?state=under-review'
 
 For all other types of requests, including ``POST`` and ``PATCH``, these
-parameters should be passed as form-encoded data:
+parameters should be encoded as JSON with a ``Content-Type`` of
+``application/json`` or passed as form-encoded data:
 
 .. code-block:: shell
 
-    $ curl -X PATCH -F 'state=under-review' \
+    $ curl -X PATCH \
+      --header "Content-Type: application/json" \
+      --data '{"state":"under-review"}' \
+      'http://localhost:8000/api/patches/123/'
+
+.. code-block:: shell
+
+    $ curl -X PATCH \
+      --form 'state=under-review' \
       'https://patchwork.example.com/api/patches/123'
 
+.. important::
+
+    If you do not include the ``Content-Type`` header in your request, you will
+    receive a ``HTTP 200 (OK)`` but the resource will not be updated. This
+    header **must** be included.
+
 .. versionchanged:: 2.1
 
    API version 1.1 allows filters to be specified multiple times. Prior to