docs: Add basic API guide

Because it is now possible to access the auto-generated XML-RPC
documentation, only provide a brief "HOWTO" on using the 'xmlrpclib'
library and a note on how to find this autogenerated documentation.

Signed-off-by: Stephen Finucane <stephen.finucane@intel.com>

1 files changed, 51 insertions, 0 deletions

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..04026d8
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,51 @@
+# The XML-RPC API
+
+Patchwork provides an XML-RPC API. This API can be used to be used to retrieve
+and modify information about patches, projects and more.
+
+**NOTE:** The XML-RPC API can be enabled/disabled by the administrator: it may
+not be available in every instance.
+
+## Patchwork API Documentation
+
+Patchwork provides automatically generated documentation for the XML-RPC API.
+You can find this at the following URL:
+
+    http://patchwork.example.com/xmlrpc/
+
+Where `patchwork.example.com` refers to the URL of your patchwork instance.
+
+**NOTE:** Automatic documentation generation for the patchwork API was
+introduced in Patchwork v1.1. Prior versions of Patchwork do not offer this
+functionality.
+
+## Developing Your Own Client
+
+You need to connect to the server. Some methods require authentication (via
+HTTP Basic Auth) while others do not. Authentication uses your patchwork
+account and the on-server documention will indicate where it is necessary.
+We will only cover the unauthenticated method here for brevity - please
+consult the [`xmlrpclib`] documentation for more detailed examples:
+
+    from __future__ import print_function
+    import sys
+    import xmlrpclib
+
+    url = 'http://patchwork.example.org/xmlrpc/'
+
+    try:
+        rpc = xmlrpclib.ServerProxy(url)
+    except:
+        print('Unable to connect to %s\n' % url, file=sys.stderr)
+        sys.exit(1)
+
+After connecting, the `rpc` object will be populated with a list of available
+functions (or procedures, in RPC terminology). For example, if we continue
+with the above example:
+
+    print(rpc.pw_rpc_version())
+
+It should be possible to use all the methods listed in the
+[server's documentation](#patchwork-api-documentation).
+
+[`xmlrpclib`]: https://docs.python.org/2/library/xmlrpclib.html