sphinx documentation

1 files changed, 64 insertions, 0 deletions

diff --git a/docs/access_api.rst b/docs/access_api.rst
new file mode 100644
index 000000000..dd3998df4
--- /dev/null
+++ b/docs/access_api.rst
@@ -0,0 +1,64 @@
+.. _access_api:
+
+*********************
+How to access the API
+*********************
+
+pyLoad has a very powerfull API with can be accessed in several ways.
+
+Overview
+--------
+
+First of all, you need to know what you can do with our API. It lets you do all common task like
+retrieving download status, manage queue, manage accounts, modify config and so on.
+
+This document is not intended to explain every function in detail, for a complete listing
+see :class:`Api <module.Api.Api>`.
+
+Of course its possible to access the ``core.api`` attribute in plugins and hooks, but much more
+interesting is the possibillity to call function from different programs written in many different languages.
+
+pyLoad uses thrift as backend and provides its :class:`Api <module.Api.Api>` as service.
+More information about thrift can be found here http://wiki.apache.org/thrift/.
+
+Using Thrift
+------------
+
+Every thrift service has to define all data structures and declare every method which should be usable via rpc.
+This file is located :file:`module/remote/thriftbackend/pyload.thrift`, its very helpful to inform about
+arguments and detailed structure of return types. However it does not contain any information about what the functions does.
+
+Assuming you want to use the API in any other language than python than check if it is
+supported here http://wiki.apache.org/thrift/LibraryFeatures?action=show&redirect=LanguageSupport.
+
+Now install thrift, for instructions see http://wiki.apache.org/thrift/ThriftInstallation.
+If every thing went fine you are ready to generate the method stubs, the command basically looks like this. ::
+
+     $thrift --gen (language) pyload.thrift
+
+You find now a directory named :file:`gen-(language)`. For instruction how to use the generated files consider the docs
+at the thrift wiki and the examples here http://wiki.apache.org/thrift/ThriftUsage
+
+
+Example
+-------
+In case you want to use python, pyload has already all files included to access the api over rpc.
+A basic script that prints out some information. ::
+
+    from module.remote.thriftbackend.ThriftClient import ThriftClient, WrongLogin
+
+    try:
+        client = ThriftClient(host="127.0.0.1", port=7227, user="User", password="yourpw")
+    except:
+        print "Login was wrong"
+        exit()
+
+    print "Server version:", client.getServerVersion()
+    print client.statusDownloads()
+    q = client.getQueue()
+    for p in q:
+      data = client.getPackageData(p.pid)
+      print "Package Name: ", data.name
+
+That's all for now, pretty easy isn't it?
+If you still have open questions come around in irc or post them at our pyload forum.
\ No newline at end of file