API Basics¶
The TeamDrive Enterprise Server architecture provides an extensive application programming interface (API) that can be used to:
- Script/automate processes that would otherwise require use of the web-based administration console
- Obtain information about various entities and parameters (e.g. user names, licenses, storage).
The API is based on XML Remote Procedure Calls
(see http://en.wikipedia.org/wiki/XML-RPC for a detailed description).
Only HTTP POST-Requests will be accepted.
Each request must include a checksum in the
URL appended as a parameter. This checksum is created by calculating a MD5
checksum over the request body appended with a server-specific salt value.
The checksum value must be provided in lower case characters, e.g. by passing
it through the tolower()
function of the respective programming language.
On the TeamDrive Registration Server Administration Console, this salt value
can be obtained from the APIChecksumSalt
system setting (“Edit Settings ->
RegServer”). On a TeamDrive Host Server, this value is stored in the
configuration setting API_SALT
and must match the value of the
Registration Server this Host Server has been associated with.
Each request also needs to include a <requesttime>
which is the current
timestamp converted to integer.
The general structure of the URL is:
http://<domain>/<YvvaApacheHandler>/<Yvva-Name>/<Module-Name>/<Handler-Name>.htm
The URL to access a TeamDrive Registration Server’s API is as follows:
https://<domain>/pbas/td2as/api/api.htm?checksum=<md5>
The URL to access the TeamDrive Host Server API looks as follows:
https://<domain>/pbas/p1_as/api/api.htm?checksum=<md5>
Please replace <domain>
with the host name of the Host or Registration
Server you want to connect to. <md5>
needs to be replaced with the
checksum of the current API request.
If you are accessing the API over a local network or a VPN, you can use plain HTTP. However, when sending the data over an insecure network, you must use HTTPS for security reasons.
Note
API access is verified by the IP address the request originated from. On the
Registration Server, check the setting API_IP_ACCESS
(“Edit Provider
Settings” -> “API” -> “API_IP_ACCESS” via the Administration Console) and
make sure that the external IP address of the system performing the API call
is included in the list.
On the Host Server, the IP address must be added to the configuration
setting API_IP_LIST
.
Example API Call¶
The following shell script example outlines how an API
call is generated and how the required MD5 checksum is calculated.
In this example curl
is used to perform the actual API call.
The result is printed to the console:
#!/bin/sh
URL="http://regserver.yourdomain.com/pbas/td2api/api/api.htm"
CHECKSUM="<APIChecksumSalt>"
TIMESTAMP=`date "+%s"`
REQUEST="<?xml version='1.0' encoding='UTF-8' ?>\
<teamdrive><apiversion>1.0.004</apiversion>\
<command>loginuser</command>\
<requesttime>$TIMESTAMP</requesttime>\
<username>YourUserName</username>\
<password>YourPassword</password></teamdrive>"
MD5=`echo -n "$REQUEST$CHECKSUM" | md5sum | cut -f1 -d" "`
curl -d "$REQUEST" "$URL?checksum=$MD5"
API Usage Recommendations¶
On your side of the (web-) application, you must ensure that only successfully logged in users can view or change their own data. Users should never be allowed to view data from other TeamDrive Users. Only users associated with your provider code can be managed with API calls coming from your IP. For users with a foreign provider code you will receive a URL which must be displayed to the user so that they can login to the website of their provider.
Error Handling¶
The following errors can occur due to misconfiguration or service failures, they may not return valid XML. Your application should handle these failures appropriately.
Wrong Apache configuration¶
Request:
http://<domain>/pbas/td2api/api/service.html
Answer:
<html><head>
<title>404 Not Found</title>
</head><body>
<h1>Not Found</h1>
<p>The requested URL /td2api/api/service.html was not found on this server.</p>
<hr>
<address>Apache/2.2.9 (Fedora) Server Port 80</address>
</body></html>
Application errors¶
Application errors will return error messages in an XML format like this:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>1.0.004</apiversion>
<exception>
<primarycode></primarycode>
<secondarycode></secondarycode>
<message></message>
</exception>
</teamdrive>
<primarycode>
and <secondarycode>
(optional) are integer values.
<message>
is a text.
Error codes regarding the API will start at -30100 (see Error Codes).
General errors with the Yvva Runtime Environment version or database connection are in the range between 0 and -23000.
Programming errors¶
If a program error occurs, the server will return an error similar to the following one:
<HTML><HEAD><TITLE>Execution Error</TITLE></HEAD><BODY>
<H2>Execution Error</H2><FONT SIZE = +1>An error occured while processing
your request: <BR>Primary error code: <B>-10005</B>, Secondary error code:
<B>0</B><BR><FONT SIZE = 0><H3>"api_init.sys"@client line 7: ';' token
expected in place of 'execute'.</H3></BODY></HTML>
Invalid Requests¶
Invalid requests will return one of the following errors:
Unknown IP Address¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>1.0.004</apiversion>
<exception>
<primarycode>-30000</primarycode>
<secondarycode></secondarycode>
<message>Access denied</message>
</exception>
</teamdrive>
Invalid Command¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>1.0.004</apiversion>
<exception>
<primarycode>-30001</primarycode>
<secondarycode></secondarycode>
<message>Invalid Command</message>
</exception>
</teamdrive>
Invalid Request¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>1.0.004</apiversion>
<exception>
<primarycode>-30002</primarycode>
<secondarycode></secondarycode>
<message>Invalid Request</message>
</exception>
</teamdrive>
Invalid XML¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>1.0.004</apiversion>
<exception>
<primarycode>-30003</primarycode>
<secondarycode></secondarycode>
<message>Invalid XML</message>
</exception>
</teamdrive>