TeamDrive Http Api ================== Overview -------- The *TeamDrive Agent* offers a JSON interface via HTTP, which allows you to operate the *TeamDrive Agent* without using the GUI. The JSON interface can be activated by specifying the :option:`teamdrived --http-api-port` option. The command line application `TeamDriveApi.py` is located in the *TeamDrive Agent* installation directory (e.g. *C:\\Program Files (x86)\\TeamDrive 3 Agent*). Running this file allows you to use the TeamDrive API directly. See :ref:`teamdrived-options` for a list of Options and Settings. If you would like to use the TeamDrive HTTP API without Python, HTTP `GET` requests can be made directly through *TeamDrive Agent*. The URL will need to be constructed as follows:: http:///api/? For example:: http://[::1]:45454/api/getSpace?id=1 The result is a JSON document. Requirements ------------ In order to run use the interface, you will need the these requirements: * TeamDrive Desktop Client or *TeamDrive Agent* The :download:`Python module and Command line interface <../../tools/HttpApi/TeamDriveApi.py>` requires * `Python` in your `PATH` variable. * Recommended: docopt for Python. * :py:func:`TeamDriveApi.TeamDriveApi.sse` requires `Python 3`. Security Considerations ----------------------- Communicating with the *TeamDrive Http Api* contains sensitive information, for example user names, passwords and file data. There are mechanisms to provide authentication and privacy. Restricting the availability of the Api ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By restricting the api to the local host, any attempt to access the api from another host will fail:: http-api-port=127.0.0.1: Although, this does not prevent the usage of the api from another user of this system. Using a local socket or a named pipe ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One can further reduce the availability by specifying the type of the api like this:: http-api-type=socket http-api-port= can be a user defined string. The Unix socket file will be placed in `/tmp` on Mac OS X and on Linux. Using HTTPS for communication with the TeamDrive Agent ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ HTTPS can be enabled by setting `type` to `ssl` like this:: http-api-type=ssl http-api-port=443 It is recommended to use port 443 for communication with browsers, because using a non-standard port for HTTPS is considered insecure. Please also have a look at the :option:`teamdrived --http-api-certificate` and :option:`teamdrived --http-api-private-key` settings. .. _authentication-label: Authentication -------------- In order to prevent unauthorized users from accessing the *TeamDrive Http Api*, an authentication is **required** to access the api. There are two ways to authenticate clients: #. Statefull Session Cookies #. Stateless Authorization Header Session Cookies ^^^^^^^^^^^^^^^ Session Cookies are mainly used to authenticate Web Browsers. Using a session requires a call to :py:func:`TeamDriveApi.TeamDriveApi.login` to retrieve a cookie from the server. :py:func:`TeamDriveApi.TeamDriveApi.getLoginInformation` can be used to determine if a login is required. .. msc { a [label="Client"], b [label="TeamDrive Agent"]; --- [label="Login"]; a =>> b [label="GET /getLoginInformation"]; b =>> a [label="200 {'loginRequired': true'}"]; a =>> b [label="POST /login\n{'username':'foo', 'password':'bar'}"]; b =>> a [label="200 Set-Cookie: SessionID=SAFD432"]; --- [label="Communication with the API"]; a =>> b [label="GET /api/getSpaces\nCookie: SessionID=SAFD432"]; b =>> a [label="200 [....]"]; a =>> b [label="POST /api/createFolder\nCookie: SessionID=SAFD432"]; b =>> a [label="200\n{...}"]; --- [label="Cookie Missing"]; a =>> b [label="GET /api/getSpaces"]; b =>> a [label="500 {'error': 50}"]; a note a [label="Go to login."]; } Login with the Api using Cookies should follow this protocol: .. image:: protocol.png In the case of a missing Cookie, a :py:attr:`TeamDriveApi.TeamDriveException.Error_Missing_Session` is returned Authorization Header ^^^^^^^^^^^^^^^^^^^^ This stateless alternative to Cookies uses HTTP Basic Authentication. **Every** request to the Api requires an *Authorization Header* following :rfc:`2617`. Currently, The Agent does *not* answer requests without Authentication Header appropriately. It is expected, that clients send the Authorization Header unconditionally. Interface Overview ------------------ TeamDrive provides two API endpoints: * The :code:`/api` endpoint provides meta data about all elements of TeamDrive * The :code:`/files` endpoint provides an interface for reading and writing the file content. Communicating with the /api endpoint ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is the reference documentation of the TeamDrive Client API. As a convenience, there is a Python module that provides accessor functions for each API call, which is also usable as a command line interface. Please have a look at all possible usages. **Example using curl**:: $ curl '127.0.0.1:45454/api/getLoginInformation' { "isLoginRequired" : true } **Example using the Python module**:: >>> from TeamDriveApi import TeamDriveApi >>> api = TeamDriveApi("127.0.0.1:45454") >>> map(api.getSpace, api.getSpaceIds()) [{.....}] **Example using the command line**:: ./TeamDriveApi.py '127.0.0.1:45454' getLoginInformation { "username": "My Username", "apiUrl": "/", "isLoginRequired": false } **Example Session (Initial Login)**: .. code:: bash # Start TeamDrive: exec /opt/teamdrive/teamdrived # Wait for it: sleep 5 # Log-in ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass login # Create a new Space ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass createSpace # Call Functions ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass createFolder # Quit TeamDrive without logout ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass quit False **Example Session**:: exec /opt/teamdrive/teamdrived sleep 5 # No need to login now ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass createFolder # Quit TeamDrive without logout ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass quit False **Example Session (After previous Logout**:: # If the previous session ended with a logout: ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass quit True # The next call should start with a login: exec /opt/teamdrive/teamdrived sleep 5 ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass login ./TeamDriveApi.py '127.0.0.1:45454' --user myUser --pass myPass createFolder .. seealso:: :class:`TeamDriveApi.TeamDriveException` for Errors returned by the API. .. seealso:: Chapter :ref:`authentication-label` regarding Authentication. Communicating with the /files endpoint ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ See :func:`TeamDriveApi.TeamDriveApi.putFile` for Details. Passing Parameters to the API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The format of parameters depend on the HTTP method: * Parameters for GET-requests should be passed by a query string in the url. For example :code:`curl --user myTeamDriveUser http://127.0.0.1:45454/api/getSpace?id=310` * Parameters to POST-requests can either be a JSON object or data encoded using :code:`application/x-www-form-urlencoded`. Interface Description --------------------- TeamDriveApi.TeamDriveApi ^^^^^^^^^^^^^^^^^^^^^^^^^ .. autoclass:: TeamDriveApi.TeamDriveApi :members: :inherited-members: TeamDriveApi.TeamDriveException ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. autoclass:: TeamDriveApi.TeamDriveException :members: :inherited-members: Change Log ========== TeamDrive 4.1.2 --------------- - added :any:`setSpaceSetting`. - added :option:`teamdrived --enable-shell-extension`. TeamDrive 4.1.1 --------------- - added :any:`setAccountEmail` - :any:`about` no longer returns license info. call :any:`getLicense` instead. - added :any:`requestResetPassword` - added :any:`getProfilePicture`, :any:`setProfilePicture`, :any:`clearProfilePicture` and :any:`setProfileInfo` - added :any:`getComments`, :any:`getSpaceComments`, :any:`addComment`, :any:`addSpaceComment` and :any:`removeComment` - deprecated :any:`getSpaceMemberIds` - added :any:`getSpacePermissionLevels`, :any:`setMemberPermissionLevel`, added permission levels to Member related calls. - added :any:`getSpaceStatistics` - added ability to handle password protected invitations in :any:`joinSpace` and :any:`inviteMember` - added :any:`getActivities` and :any:`getActivityDetails` - added :option:`teamdrived --idle-shutdown-timeout`, :option:`teamdrived --http-api-external-register-url` and :option:`teamdrived --http-api-external-login-url` TeamDrive 4.1 ------------- - Added :any:`createFolder`, :any:`publishFile` and :any:`unpublishFile`. - Added documentation of the `/sse` API TeamDrive 4.0 ------------- - All modifying calls require HTTP POST requests, for example createFolder or deleteSpace - Client Authentication is **required** - Added :any:`getSpaces`, :any:`getFullFolderContent`, :any:`getFullAddressbook`, :any:`setTrashed` and :any:`createFolder` - Changed the Exception response. - added :any:`getMember` to retrieve the status of a member TeamDrive 3.3.1 --------------- - added :any:`getSpaceMemberIds` Web User Interface 1.0.2 ------------------------ * Create Space Dialog: Added Server selection. (Requires Agent 4.1.2). * Improved error message if there is no depot usage available. * Added automatic redirect to the external login url on the login page. * Fixed a bug regarding custom user rights (Only TeamDrive 3 Spaces affected)