diff options
Diffstat (limited to 'docs/development/xmlrpc.md')
-rw-r--r-- | docs/development/xmlrpc.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/docs/development/xmlrpc.md b/docs/development/xmlrpc.md new file mode 100644 index 0000000..cfa5acf --- /dev/null +++ b/docs/development/xmlrpc.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 documentation 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 |