From 9ebdb33dcd859e02e02aff628922047c865e7124 Mon Sep 17 00:00:00 2001 From: RaNaN Date: Mon, 9 Jan 2012 21:29:18 +0100 Subject: updated docs --- docs/api/json_api.rst | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/api/json_api.rst (limited to 'docs/api/json_api.rst') diff --git a/docs/api/json_api.rst b/docs/api/json_api.rst new file mode 100644 index 000000000..3df006c49 --- /dev/null +++ b/docs/api/json_api.rst @@ -0,0 +1,72 @@ +.. _json_api: + +======== +JSON API +======== + +JSON [1]_ is a lightweight object notation and wrapper exists for nearly every programming language. Every +modern browser is able to load JSON objects with JavaScript. Unlike to thrift you don't need to generate or precompile +any stub methods, the JSON :class:`Api ` is ready to use for most language. The libary is really lightweight (at least in python) +and you can build very lightweight scripts with it. Because of the builtin support JSON is the first choice for all browser +applications. + +In our case JSON is just the output format, you have exactly the same methods available as with the thrift backend. The only +difference is the used protocol. + +So are there still reasons to choose the original :doc:`thrift ` backend in favor to JSON? Yes, since it +uses a binary protocol the performance will be better (when generating the objects), traffic will be smaller and +therefore the transfer faster. +In most IDEs you will get code completion, because of the pre-generated classes, which can make work much easier. + +If you intend to write a full client you should prefer thrift if the language is supported, for lightweight scripts and +in browser environment JSON wil be the better choice. + +Login +----- + +First you need to authenticate, if you using this within the webinterface and the user is logged the API is also accessible, +since they share the same cookie/session. + +However, if you are building a 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 dont'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 ` documentation, which is also available to +the thriftbackend. + +Access works simply via ``http://pyload-core/api/methodName``, where ``pyload-core`` is the ip address +or hostname including the webinterface 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 datatypes can be found +:doc:`here ` + +Passing parameters +------------------ + +To pass arguments you have two choices. +Either use positional arguments, eg ``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 ` 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 intergers, 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 have to be urlencoded at last. (Most libaries will do that automatically) + + +.. rubric:: Footnotes + +.. [1] http://de.wikipedia.org/wiki/JavaScript_Object_Notation \ No newline at end of file -- cgit v1.2.3 From 5a7f415a25d8e036a37851fcd5e9be81caae2804 Mon Sep 17 00:00:00 2001 From: X3n0m0rph59 Date: Sun, 22 Apr 2012 16:54:06 +0200 Subject: Fixed spelling in the documentation --- docs/api/json_api.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs/api/json_api.rst') diff --git a/docs/api/json_api.rst b/docs/api/json_api.rst index 3df006c49..6d55b13b4 100644 --- a/docs/api/json_api.rst +++ b/docs/api/json_api.rst @@ -4,35 +4,35 @@ JSON API ======== -JSON [1]_ is a lightweight object notation and wrapper exists for nearly every programming language. Every +JSON [1]_ is a lightweight object notation and wrappers exist for nearly every programming language. Every modern browser is able to load JSON objects with JavaScript. Unlike to thrift you don't need to generate or precompile -any stub methods, the JSON :class:`Api ` is ready to use for most language. The libary is really lightweight (at least in python) -and you can build very lightweight scripts with it. Because of the builtin support JSON is the first choice for all browser +any stub methods, the JSON :class:`Api ` is ready to be used in most languages. The library is really lightweight (at least in python) +and you can build very lightweight scripts with it. Because of the builtin support, JSON is the first choice for all browser applications. In our case JSON is just the output format, you have exactly the same methods available as with the thrift backend. The only -difference is the used protocol. +difference is the underlying protocol. -So are there still reasons to choose the original :doc:`thrift ` backend in favor to JSON? Yes, since it +Are there still reasons to choose the original :doc:`thrift ` backend in favor to JSON? Yes, since it uses a binary protocol the performance will be better (when generating the objects), traffic will be smaller and therefore the transfer faster. In most IDEs you will get code completion, because of the pre-generated classes, which can make work much easier. If you intend to write a full client you should prefer thrift if the language is supported, for lightweight scripts and -in browser environment JSON wil be the better choice. +in browser environments JSON will be the better choice. Login ----- -First you need to authenticate, if you using this within the webinterface and the user is logged the API is also accessible, +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 a external client and want to authenticate manually +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 dont't have cookies enabled you can pass the session id as ``session`` POST parameter +In case you don't have cookies enabled you can pass the session id as ``session`` POST parameter so pyLoad can authenticate you. @@ -40,19 +40,19 @@ Calling Methods --------------- In general you can use any method listed at the :class:`Api ` documentation, which is also available to -the thriftbackend. +the thrift backend. Access works simply via ``http://pyload-core/api/methodName``, where ``pyload-core`` is the ip address -or hostname including the webinterface port. By default on local access this would be `localhost:8000`. +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 datatypes can be found +The return value will be formatted in JSON, complex data types as dictionaries. Definition for data types can be found :doc:`here ` Passing parameters ------------------ -To pass arguments you have two choices. -Either use positional arguments, eg ``http://pyload-core/api/getFileData/1``, where 1 is the FileID, or use keyword +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 ` documentation. @@ -60,11 +60,11 @@ It is important that *all* arguments are in JSON format. So ``http://pyload-core 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 intergers, 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. +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 have to be urlencoded at last. (Most libaries will do that automatically) +Please note that the data has to be urlencoded at last. (Most libraries will do that automatically) .. rubric:: Footnotes -- cgit v1.2.3 From e8eaa91da9e1236d8009df0d79bebe023de8933f Mon Sep 17 00:00:00 2001 From: RaNaN Date: Sun, 6 May 2012 13:04:15 +0200 Subject: little documentation update --- docs/api/json_api.rst | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'docs/api/json_api.rst') diff --git a/docs/api/json_api.rst b/docs/api/json_api.rst index 6d55b13b4..bcf546dc0 100644 --- a/docs/api/json_api.rst +++ b/docs/api/json_api.rst @@ -66,7 +66,41 @@ 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 \ No newline at end of file +.. [1] http://de.wikipedia.org/wiki/JavaScript_Object_Notation -- cgit v1.2.3