1 files changed, 95 insertions, 0 deletions
diff --git a/docs/api/json_api.rst b/docs/api/json_api.rst
new file mode 100644
index 000000000..504de20bf
--- /dev/null
+++ b/docs/api/json_api.rst
@@ -0,0 +1,95 @@
+.. _json_api:
+
+========
+JSON API
+========
+
+JSON [1]_ is a lightweight object notation and wrappers exists for nearly every programming language. Every
+modern browser is able to load JSON objects with JavaScript. Unlike other RPC methods you don't need to generate or precompile
+any stub methods. The JSON :class:`Api <pyload.Api.Api>` is ready to be used in most languages and most JSON libraries are lightweight
+enough to build very small and performant scripts. Because of the builtin support, JSON is the first choice for all browser
+applications.
+
+Login
+-----
+
+First you need to authenticate, if you are using this within the web interface and the user is logged in, the API is also accessible,
+since they share the same cookie/session.
+
+However, if you are building an external client and want to authenticate manually
+you have to send your credentials ``username`` and ``password`` as
+POST parameter to ``http://pyload-core/api/login``.
+
+The result will be your session id. If you are using cookies, it will be set and you can use the API now.
+In case you don't have cookies enabled you can pass the session id as ``session`` POST parameter
+so pyLoad can authenticate you.
+
+
+Calling Methods
+---------------
+
+In general you can use any method listed at the :class:`Api <pyload.Api.Api>` documentation, which is also available to
+the thrift backend.
+
+Access works simply via ``http://pyload-core/api/methodName``, where ``pyload-core`` is the ip address
+or hostname including the web interface port. By default on local access this would be `localhost:8000`.
+
+The return value will be formatted in JSON, complex data types as dictionaries. Definition for data types can be found
+:doc:`here <datatypes>`
+
+Passing parameters
+------------------
+
+To pass arguments you have two choices:
+Either use positional arguments, e.g.: ``http://pyload-core/api/getFileData/1``, where 1 is the FileID, or use keyword
+arguments supplied via GET or POST ``http://pyload-core/api/getFileData?fid=1``. You can find the argument names
+in the :class:`Api <pyload.Api.Api>` documentation.
+
+It is important that *all* arguments are in JSON format. So ``http://pyload-core/api/getFileData/1`` is valid because
+1 represents an integer in json format. On the other hand if the method is expecting strings, this would be correct:
+``http://pyload-core/api/getUserData/"username"/"password"``.
+
+Strings are wrapped in double qoutes, because `"username"` represents a string in JSON format. It's not limited to
+strings and integers, every container type like lists and dicts are possible. You usually don't have to convert them.
+Just use a JSON encoder before using them in the HTTP request.
+
+Please note that the data has to be urlencoded at last. (Most libraries will do that automatically)
+
+Example
+-------
+
+Here is a little python script that is able to send commands to the pyload api::
+
+    #!/usr/bin/env python
+    # -*- coding: utf-8 -*-
+
+    from urllib import urlopen, urlencode
+    from json import dumps
+
+    URL = "http://localhost:8001/api/%s"
+
+    def login(user, pw):
+        params = {"username": user, "password": pw}
+        ret = urlopen(URL % "login", urlencode(params))
+        return ret.read().strip("\"")
+
+    # send arbitrary command to pyload api, parameter as keyword argument
+    def send(session, command, **kwargs):
+        # convert arguments to json format
+        params = dict([(k, dumps(v)) for k,v in kwargs.iteritems()])
+        params["session"] = session
+        ret = urlopen(URL % command, urlencode(params))
+        return ret.read()
+
+    if __name__ == "__main__":
+        session = login("User", "pwhere")
+        print "Session id:", session
+
+        result = send(session, "setCaptchaResult", tid=0, result="some string")
+        print result
+
+
+
+.. rubric:: Footnotes
+
+.. [1] http://de.wikipedia.org/wiki/JavaScript_Object_Notation