docs: Add REST API usage guide

This details the availability of 'git-pw'. The other API usage and
development guides are updated accordingly.

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

2 files changed, 68 insertions, 6 deletions

diff --git a/docs/development/rest.rst b/docs/development/rest.rst
new file mode 100644
index 0000000..efab9f4
--- /dev/null
+++ b/docs/development/rest.rst
@@ -0,0 +1,67 @@
+The REST API
+============
+
+Patchwork provides a REST API. This API can be used to retrieve and modify
+information about patches, projects and more.
+
+This guide covers development information for the Patchwork REST API. For
+information on using the REST API, refer to `rest`. For information on general
+usage of the REST API, refer to :doc:`../usage/rest`.
+
+.. versionadded:: 2.0
+
+   The REST API was introduced in Patchwork v2.0. Users of earlier Patchwork
+   versions should instead refer to :doc:`xmlrpc`.
+
+Documentation
+-------------
+
+Patchwork provides automatically generated documentation for the REST API.
+You can find this at the following URL:
+
+    http://patchwork.example.com/api/
+
+where `patchwork.example.com` refers to the URL of your Patchwork instance.
+
+Interacting with the API
+------------------------
+
+REST APIs run over plain HTTP(S), thus, the API can be interfaced using
+applications or libraries that support this widespread protocol. One such
+application is `curl`__, which can be used to both retrieve and send
+information to the REST API. For example, to get the version of the REST API
+for a Patchwork instance hosted at `patchwork.example.com`, run:
+
+.. code-block:: shell
+
+    $ curl -s http://localhost:8000/api/1.0/ | python -m json.tool
+    {
+        "patches": "http://localhost:8000/api/1.0/patches/",
+        "people": "http://localhost:8000/api/1.0/people/",
+        "projects": "http://localhost:8000/api/1.0/projects/",
+        "users": "http://localhost:8000/api/1.0/users/"
+    }
+
+In addition, a huge variety of libraries are available for interacting with and
+parsing the output of REST APIs. The `requests`__ library is wide-spread and
+well-supported. To repeat the above example using `requests`:
+
+.. code-block:: pycon
+
+    $ python
+    >>> import json
+    >>> import requests
+    >>> r = requests.get('http://patchwork.example.com/api/1.0/')
+    >>> print(json.dumps(r.json(), indent=2))
+    {
+          "users": "http://localhost:8000/api/1.0/users/",
+          "patches": "http://localhost:8000/api/1.0/patches/",
+          "projects": "http://localhost:8000/api/1.0/projects/",
+          "people": "http://localhost:8000/api/1.0/people/"
+    }
+
+Tools like `curl` and libraries like `requests` can be used to build anything
+from small utilities to full-fledged clients targeting the REST API.
+
+__ https://curl.haxx.se/
+__ http://docs.python-requests.org/en/master/
diff --git a/docs/development/xmlrpc.rst b/docs/development/xmlrpc.rst
index 9842c78..4b2651f 100644
--- a/docs/development/xmlrpc.rst
+++ b/docs/development/xmlrpc.rst
@@ -8,11 +8,6 @@ This guide covers development information for the Patchwork XML-RPC API. For
 information on using the REST API, refer to `rest`. For information on general
 usage of the XML-RPC API, refer to :doc:`../usage/xmlrpc`.
 
-.. note::
-
-   The XML-RPC API can be enabled/disabled by the administrator: it may not be
-   available in every instance.
-
 Documentation
 -------------
 
@@ -23,7 +18,7 @@ You can find this at the following URL:
 
 where `patchwork.example.com` refers to the URL of your Patchwork instance.
 
-.. note::
+.. versionchanged:: 1.1
 
    Automatic documentation generation for the Patchwork API was introduced in
    Patchwork v1.1. Prior versions of Patchwork do not offer this functionality.