.. _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