docs: Add basic REST API documentation

This is only user-facing for now. Developer focused docs can be added
later.

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

2 files changed, 60 insertions, 2 deletions

diff --git a/docs/usage/rest.md b/docs/usage/rest.md
new file mode 100644
index 0000000..e0fbf24
--- /dev/null
+++ b/docs/usage/rest.md
@@ -0,0 +1,56 @@
+# The REST API
+
+Patchwork provides a REST API. This API can be used to retrieve and modify
+information about patches, projects and more.
+
+**NOTE:** The REST API was introduced in Patchwork v2.0. Users of earlier
+Patchwork versions should instead refer to the [XML-RPC API
+documentation][doc-xmlrpc].
+
+## Patchwork REST API documentation
+
+Patchwork provides automatically generated documentation for the RESET 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`][ref-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:
+
+    $ 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 avaiable for interacting with and
+parsing the output of REST APIs. The [`requests`][ref-requests] library is
+wide-spread and well-supported. To repeat the above example using `requests`:
+
+    $ 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.
+
+[doc-xmlrpc]: xmlrpc.md
+[ref-curl]: https://curl.haxx.se/
+[ref-requests]: http://docs.python-requests.org/en/master/
diff --git a/docs/usage/xmlrpc.md b/docs/usage/xmlrpc.md
index de95a07..782edae 100644
--- a/docs/usage/xmlrpc.md
+++ b/docs/usage/xmlrpc.md
@@ -1,8 +1,9 @@
 # The XML-RPC API
 
 **NOTE:** This guide covers usage information for the Patchwork XML-RPC API.
-For information on developing custom applications or clients for this API,
-refer to the [developers documentation][doc-development].
+For information on using the REST API, refer to the [REST API
+documentation][doc-rest]. For information on developing custom applications or
+clients for this API, refer to the [developers documentation][doc-development].
 
 Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
 and modify information about patches, projects and more.
@@ -35,3 +36,4 @@ Once downloaded, to view information about all the operations supported by
     $ pwclient --help
 
 [doc-development]: ../development/xmlrpc.md
+[doc-rest]: rest.md