[PATCH 3/3] docs: Add basic API guide

[Stephen Finucane]

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 at intel.com>
---
 docs/api.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/api.md

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..9bd674a
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,50 @@
+# 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. We will only cover the unauthenticated method here for brevity -
+please consult the [documentation] for more detailed examples:
+
+    from __future__ import print_function
+    import sys
+    import xmlrpclib
+
+    url = 'http://patchwork.example.org/xmlrpc/'
+
+    try:
+        rpc = xmlrpclib.Server(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 servers
+documentation.
+
+[documentation]: https://docs.python.org/2/library/xmlrpclib.html
+
-- 
2.0.0