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. .. note:: The HTTPS server that is used by the TeamDrie Agent is based on the Qt framework, which supports, according to the `documentation `_, the following protocols: ``SSLv2``, ``SSLv3``, ``TLSv1.0``, ``TLSv1.1`` and ``TLSv1.2``. .. _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: Common JSON Data Types ---------------------- The API returns common data types encoded in JSON objects for different API functions. This section provides an overview of some of these data types. .. _space-json-data-type: Space ^^^^^ This JSON object describes meta information about a single Space. +-------------------------+---------------------------------------------------------------------------------+ | Member | Description | +=========================+=================================================================================+ | ``id`` | Id of the Space. Used to identify a specific Space | +-------------------------+---------------------------------------------------------------------------------+ | ``fileId`` | FileId of the root-folder in this Space. Only present for active Spaces | +-------------------------+---------------------------------------------------------------------------------+ | ``name`` | Name of the Space | +-------------------------+---------------------------------------------------------------------------------+ | ``spaceRoot`` | Local path to the Space. | +-------------------------+---------------------------------------------------------------------------------+ | ``invitor`` | Invitations only: User name who created the invitation. | +-------------------------+---------------------------------------------------------------------------------+ | ``creator`` | User name who created the Space | +-------------------------+---------------------------------------------------------------------------------+ | ``icon`` | Space icon. | +-------------------------+---------------------------------------------------------------------------------+ | ``status`` | Status of the Space. | +-------------------------+---------------------------------------------------------------------------------+ | ``status_message`` | Describes the current status of this Space. | +-------------------------+---------------------------------------------------------------------------------+ | ``hasTrashedFiles`` | Has trashed files in the Space. | +-------------------------+---------------------------------------------------------------------------------+ | ``isPasswordProtected`` | Invitations only: This invitation needs a password. Obmitted if false. | +-------------------------+---------------------------------------------------------------------------------+ | ``time`` | Datetime of the last modification of this Space. | +-------------------------+---------------------------------------------------------------------------------+ | ``text`` | Invitation comment | +-------------------------+---------------------------------------------------------------------------------+ | ``permissionLevel`` | Permission level of the current user in this Space. (Not for invitations) | +-------------------------+---------------------------------------------------------------------------------+ | ``hasComments`` | Space has comments. (Not for invitations) | +-------------------------+---------------------------------------------------------------------------------+ | ``newComments`` | Amount of new comments in the Space. (Not for invitations) | +-------------------------+---------------------------------------------------------------------------------+ | ``isOfflineAvailable`` | "true", if the Space will be synchronized to the local file system. TeamDrive | | | will only synchronize meta-data if this is `false` (Not for invitations) | +-------------------------+---------------------------------------------------------------------------------+ Example: .. code-block:: json { "name": "Api", "creator": "...", "spaceRoot": "/home/teamdrive/Spaces/Api", "icon": "space", "status": "active", "status_message": "OK", "id": 8, "fileId": 1 } .. _file-json-data-type: File ^^^^ This JSON object describes meta information about a single File or diretory. +------------------------+-----------------------------------------------------------------+ | Member | Description | +========================+=================================================================+ | ``name`` | File or Folder Name | +------------------------+-----------------------------------------------------------------+ | ``id`` | Local Id. Mainly used as parameter. | +------------------------+-----------------------------------------------------------------+ | ``spaceId`` | Space Id of the file. | +------------------------+-----------------------------------------------------------------+ | ``path`` | Path to the file excluding the name. | +------------------------+-----------------------------------------------------------------+ | ``currentVersionId`` | Version id that should be in the file system | +------------------------+-----------------------------------------------------------------+ | ``isDir`` | Boolean value. ``true`` for directories. | +------------------------+-----------------------------------------------------------------+ | ``hasNameConflict`` | File or Folder has a name conflict | +------------------------+-----------------------------------------------------------------+ | ``hasVersionConflict`` | File has a version conflict | +------------------------+-----------------------------------------------------------------+ | ``permissions`` | Unix permissions | +------------------------+-----------------------------------------------------------------+ | ``creator`` | User name of the file creator. | +------------------------+-----------------------------------------------------------------+ | ``created`` | file creation time. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``icon`` | icon name based on the file extension. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``confirmed`` | The current version is synchronized to the server. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``size`` | The size in bytes of the current version. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``time`` | file creation time. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``lastModified`` | Last modification time. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``publicUrl`` | URL to the file if it is published. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``hasComments`` | Boolean value. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``isLockedByMe`` | Boolean value. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``isLockedByOther`` | Boolean value. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``trasher`` | User name who deleted the file. (Files only) | +------------------------+-----------------------------------------------------------------+ | ``trashed`` | deletion time. (Files only) | +------------------------+-----------------------------------------------------------------+ Example: .. code-block:: json { "isDir": true, "name": "My folder", "currentVersionId": 0, "spaceId": 3, "isInFileSystem": true, "path": "/", "id": 756, "permissions": "rwxr-xr-x" } .. _addressbook-json-data-type: Addressbook Entry ^^^^^^^^^^^^^^^^^ This JSON object describes meta information about a addressbook entry. +--------------+----------------------+ | Member | Description | +==============+======================+ | ``id`` | Addressbook entry Id | +--------------+----------------------+ | ``name`` | User display name | +--------------+----------------------+ | ``email`` | Registration Email | +--------------+----------------------+ | ``profile`` | Profile information | +--------------+----------------------+ | ``initials`` | User's initials | +--------------+----------------------+ Where Profile information is a JSON object containing: +-----------------------+----------------------------------------------------------+ | Member | Description | +=======================+==========================================================+ | ``email`` | Display Email | +-----------------------+----------------------------------------------------------+ | ``phone`` | Phone number | +-----------------------+----------------------------------------------------------+ | ``mobile`` | Mobile nuber | +-----------------------+----------------------------------------------------------+ | ``hasProfilePicture`` | Boolean value. ``true`` for User's with profile picture. | +-----------------------+----------------------------------------------------------+