From: Stephen Finucane <stephen.finucane@intel.com>
Date: Sat, 10 Oct 2015 03:05:27 +0000 (+0100)
Subject: docs: Add basic API guide
X-Git-Tag: v1.1.0~203
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d4b4208c11687ecdab1cf855681fdc231908462e;p=thirdparty%2Fpatchwork.git

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>
---

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 00000000..04026d85
--- /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