diff options
Diffstat (limited to 'docs/api/json_api.rst')
| -rw-r--r-- | docs/api/json_api.rst | 36 |
1 files changed, 18 insertions, 18 deletions
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 <module.Api.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 <module.Api.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 <thrift_api>` backend in favor to JSON? Yes, since it +Are there still reasons to choose the original :doc:`thrift <thrift_api>` 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 <module.Api.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 <datatypes>` 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 <module.Api.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 |