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 ea43095c75e9c387b04f50ee566c801fe76d8fe3..6b11ac77c7a0630e69166fdad9c74aa2a829de8e 100644 (file)
--- 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