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>

diff --git a/docs/development/xmlrpc.md b/docs/development/xmlrpc.md
index 141dec93d68af48d92371e02306f67e32dc5491a..1ebc540fe05f0d741a3e10ef8554c5992786024a 100644 (file)
--- a/docs/development/xmlrpc.md
+++ b/docs/development/xmlrpc.md
@@ -1,8 +1,9 @@
 # The XML-RPC API
 
 **NOTE:** This guide covers development information for the Patchwork XML-RPC
-API. For general usage of the API, refer to the [usage
-documentation][doc-usage].
+API. For information on using the REST API, refer to the [REST API
+documentation][doc-rest]. For information on general usage of the XML-RPC API,
+refer to the [user documentation][doc-usage].
 
 Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
 and modify information about patches, projects and more.
@@ -48,5 +49,6 @@ functions (or procedures, in RPC terminology). In the above example, we used
 the `pw_rpc_version` method, however, it should be possible to use all the
 methods listed in the [server documentation](#patchwork-api-documentation).
 
+[doc-rest]: ../usage/rest.md
 [doc-usage]: ../usage/xmlrpc.md
 [ref-xmlrpclib]: https://docs.python.org/2/library/xmlrpclib.html

diff --git a/docs/usage/rest.md b/docs/usage/rest.md
new file mode 100644 (file)
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 de95a070e0b77a1fc3c2740c2872479db2cc85e3..782edaee382d0a41b0ba399b2c5c8d7c1e6e89f2 100644 (file)
--- 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

diff --git a/mkdocs.yml b/mkdocs.yml
index 5980ac988bda6838cb0e7d545440d9c8d6d25fa1..0332f461a9c1f11e6f9f7e67fb88e149924dfdeb 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,4 +15,5 @@ pages:
    - Installation: 'deployment/installation.md'
    - Upgrading: 'deployment/upgrading.md'
  - Usage Guide:
+   - REST API: 'usage/rest.md'
    - XML-RPC API: 'usage/xmlrpc.md'