Hosting Service API¶
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 MD5 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 Hosting Service, this value is stored in the
configuration setting APISalt
and must match the value of the
Registration Server this Hosting Service has been associated with.
Each request also needs to include a <requesttime>
which is the current
timestamp converted to integer.
The URL to access the TeamDrive Hosting Service 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 Distributor
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 Hosting Service, the IP address must be added to the configuration
setting APIAccessList
.
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://hostserver.local/pbas/p1_as/api/api.htm"
CHECKSUM="d3b07384d113edec49eaa6238ad5ff00"
TIMESTAMP=`date "+%s"`
REQUEST="<?xml version='1.0' encoding='UTF-8' ?>\
<teamdrive><apiversion>3.0.003</apiversion>\
<command>getdepotdata</command>\
<requesttime>$TIMESTAMP</requesttime>\
<username>YourUserName</username>\
</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 distributor code can be managed with API calls coming from your IP. For users with a foreign distributor code you will receive a URL which must be displayed to the user so that they can login to the website of their distributor.
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/p1_as/api/service.html
Answer:
<html><head>
<title>404 Not Found</title>
</head><body>
<h1>Not Found</h1>
<p>The requested URL /pbas/p1_as/api/service.html was not found on this server.</p>
<hr>
<address>Apache/2.2.9 (Fedora) Server Port 80</address>
</body></html>
Apache handler could not be addressed¶
Request:
http://<domain>/pbas/p1_as/api/service.html
Answer:
<head><TITLE>503 Service Unavailable</TITLE></head><body><H1>503 Service
Unavailable</H1><P><H3>Error Processing Request</H3></body> The following
error occurred in \'SendCGIRequest("td2api")\' while processing
your request: -12996 (-12946).
Application errors¶
Application errors will return error messages in an XML format like this:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.003</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 API Error Codes).
General errors with the PrimeBase Virtual Machine 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 occurred 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>3.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>3.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>3.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>3.0.004</apiversion>
<exception>
<primarycode>-30003</primarycode>
<secondarycode></secondarycode>
<message>Invalid XML</message>
</exception>
</teamdrive>
Requirements¶
A TeamDrive user can have different Depots on different Hosting Services. A record of which user has which depot can be stored on the Registration Server using “setdepotforuser” or in your own system by storing the username, the Hosting Service URL and the depot id.
Retrieve Depot Information¶
Note
This request must be sent to each Hosting Service where the user has a Depot.
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>getdepotdata</command>
<requesttime></requesttime>
<username></username>
</teamdrive>
Reply:
Note
Storage and transfer quantities are in Bytes: 1 KB = 1024 Bytes
.
<userlist>
is a list of Usernames which can access
the depot to create spaces.
This list is empty for a default depot.
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<depotdata>
<depot>
<depotid></depotid>
<name></name>
<status></status>
<accountnumber></accountnumber>
<created></created>
<storagelimit></storagelimit>
<storageused></storageused>
<transferlimit></transferlimit>
<transferused></transferused>
<userlist></userlist>
</depot>
<depot>...</depot>
<depot>...</depot>
</depotdata>
</teamdrive>
Retrieve Space Information¶
Note
This request must be sent to each Hosting Service where the user has a Depot.
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>getspacedata</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
</teamdrive>
Reply:
Note
Storage and transfer quantities are in Bytes: 1 KB = 1024 Bytes
.
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<spacedata>
<space>
<spaceid></spaceid>
<name></name>
<created></created>
<owner></owner>
<status></status>
<lastaccess></lastaccess>
<storageused></storageused>
<transferused></transferused>
</space>
<space>...</space>
<space>...</space>
</spacedata>
</teamdrive>
Note
The space name field is empty by default for security reasons.
You can enable the returning of space names by setting the configuration
options StoreSpaceNames
and APIReturnSpaceNames
to True
via the
TeamDrive Hosting Service Administration Console.
Error Cases¶
No Depot on the Server for the User¶
See above.
Depot-ID or the Combination of Username and Depot-ID is Unknown¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30302</primarycode>
<secondarycode></secondarycode>
<message>Depot-ID does not match</message>
</exception>
</teamdrive>
Delete Depot¶
Important
This call will also delete all of the user’s spaces
Added in 3.0.004:
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>deletedepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Activate Depot (added in 3.0.004)¶
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>activatedepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Deactivate Depot (added in 3.0.002)¶
Added in 3.0.004:
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>deactivatedepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Delete a Space¶
Note
<spaceidlist>
is a comma separated list of space-id’s.
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>deletespace</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<spaceidlist></spaceidlist>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Error Cases¶
No Depot on the Server for the User¶
See above.
Depot-ID or the Combination of Username and Depot-ID is Unknown¶
See above.
Space-ID or Combination of Space-ID and Depot-ID is Unknown¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30303</primarycode>
<secondarycode></secondarycode>
<message>Space-ID does not match</message>
</exception>
</teamdrive>
Set Depot Limits (added in 3.0.003)¶
Note
The values of <disclimit>
and <trafficlimit>
is in Bytes:
1 KB = 1024 Bytes
.
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>setdepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<disclimit></disclimit>
<trafficlimit></trafficlimit>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Error Cases¶
No Depot on the Server for the User¶
See above.
Depot-ID or the Combination of Username and Depot-ID is Unknown¶
See above.
Increasing Depot Failed due to Invalid or Wrong Disclimit or Trafficlimit¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30304</primarycode>
<secondarycode></secondarycode>
<message>Increasing Depot failed</message>
</exception>
</teamdrive>
Increase Depot Limits¶
Note
The value of <increaselimit>
is in Bytes: 1 KB = 1024 Bytes
.
Added in 3.0.003:
<increasetraffic>
: value is optional; if empty, the storage limit * 10 will be used for the traffic limit
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>increasedepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<increaselimit></increaselimit>
<increasetraffic></increasetraffic>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Error Cases¶
No Depot on the Server for the User¶
See above.
Depot-ID or the Combination of Username and Depot-ID is Unknown¶
See above.
Increasing Depot Failed due to Invalid or Wrong increaselimit¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30304</primarycode>
<secondarycode></secondarycode>
<message>Increasing Depot failed</message>
</exception>
</teamdrive>
Decrease Depot Limits¶
Note
The value of <decreaselimit>
is in Bytes: 1 KB = 1024 Bytes
.
Added in 3.0.003:
<decreasetraffic>
: value is optional; if empty, the storage limit * 10 will be used for the traffic limit
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>decreasedepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<decreaselimit></decreaselimit>
<decreasetraffic></decreasetraffic>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Error Cases¶
No Depot on the Server for the User¶
See above.
Depot-ID or the Combination of Username and Depot-ID is Unknown¶
See above.
Decreasing Depot Failed due to Invalid or Wrong Decreaselimit¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30305</primarycode>
<secondarycode></secondarycode>
<message>Decreasing Depot failed</message>
</exception>
</teamdrive>
Authorize Users to Create Spaces in other Depots¶
Note
<userlist>
is a comma seperated list of usernames
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>addusertodepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<userlist></userlist>
</teamdrive>
Reply:
Note
The reply will return a base64 encoded text in the <depotdocument>
-Tag.
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
<depotdocument></depotdocument>
</teamdrive>
Remove Authorization from Users to Create Spaces in Other depots¶
Note
<userlist>
is a comma separated list of usernames
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>deleteuserfromdepot</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<userlist></userlist>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Update Contract (added in 3.0.002)¶
Note
<username>
is optional
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>updatecontract</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
<accountnumber></accountnumber>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Create and Deploy a Depot¶
Note
Creating a new depot and deploying the depot file to a list of users must be done by executing a few requests to different servers. It depends on whether you want to use your own Host Server or the TeamDrive Cloud Host Server.
If you are using the TeamDrive Cloud Host Servers, you have to send a gethostfordepot request to the TeamDrive Registration Server. The reply will return a Hosting Service-URL dependant on your distributor code.
Send the createdepot-request to the returned URL or directly to your own Host Server, if you are using one. The reply will return a depot-document. Send this document, together with a list of usernames, to the TeamDrive Registration Server using the “sendinvitation” request as described above.
Requesting a Hosting Service-URL¶
Note
In <location>
send “EU”, “US”, or the IP-Address of the user.
The <location>
will only supported if the distributor has servers in
different locations running. Otherwise the default Hosting Service will be used.
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>gethostfordepot</command>
<requesttime></requesttime>
<username></username>
<location></location>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<hosturl></hosturl>
</teamdrive>
Error Cases¶
User Unknown¶
See above
Account not Activated¶
See above
Invalid Location¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30112</primarycode>
<secondarycode></secondarycode>
<message>Invalid location</message>
</exception>
</teamdrive>
Create Depot¶
Note
<userlist>
is a comma separated list of usernames
(this parameter is optional).
Added in 3.0.004:
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>createdepot</command>
<requesttime></requesttime>
<username></username>
<storagelimit></storagelimit>
<trafficlimit></trafficlimit>
<userlist></userlist>
<changeinfo></changeinfo>
</teamdrive>
Reply:
Note
The reply will return a base64 encoded text in the <depotdocument>
-Tag,
which must be send as an sendinvitation
request, with the list of users,
to the Registration Server (see Registration Server API “send invitation”
using the command “sendinvitation”).
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<depotdocument>...</depotdocument>
</teamdrive>
Error Cases¶
Creating depot failed due to invalid Depot-ID¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30302</primarycode>
<secondarycode></secondarycode>
<message>Depot-ID does not match</message>
</exception>
</teamdrive>
Creating Depot Failed due to Invalid Storage Limit¶
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<exception>
<primarycode>-30306</primarycode>
<secondarycode></secondarycode>
<message>Invalid storage limit</message>
</exception>
</teamdrive>
Create Depot Without User (added in 3.0.002)¶
Note
The request is similar to createdepot. Might be useful if a shop application wanted to retrieve a depot before the user has an account in the shop.
Added in 3.0.004:
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>createdepotwithoutuser</command>
<requesttime></requesttime>
<accountnumber></accountnumber>
<depotname></depotname>
<storagelimit></storagelimit>
<trafficlimit></trafficlimit>
<changeinfo></changeinfo>
</teamdrive>
Reply:
Note
The reply will include the depot id.
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult></intresult>
</teamdrive>
Assign User to Depot (added in 3.0.002)¶
Note
This request should be used if the depot was created using the createdepotwithoutuser call. If the user does not exist yet, they will be created.
Added in 3.0.004:
<changeinfo>
: can be used as a free text field for the change history
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>assignusertodepot</command>
<requesttime></requesttime>
<depotid></depotid>
<username></username>
<email></email>
<language></language>
<gender></gender>
<changeinfo></changeinfo>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<intresult>0</intresult>
</teamdrive>
Get Depot Document¶
Request:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<command>getdepotdocument</command>
<requesttime></requesttime>
<username></username>
<depotid></depotid>
</teamdrive>
Reply:
<?xml version='1.0' encoding='UTF-8' ?>
<teamdrive>
<apiversion>3.0.004</apiversion>
<depotdocument>...</depotdocument>
</teamdrive>