TeamDesk REST API

Today, we’ve released REST API for TeamDesk. REST API was designed from the ground up to address SOAP API shortcomings, simplify programming and enable integration with other REST-enabled services.

Web landscape has changed since we released SOAP API for TeamDesk back in 2006. Now, many web sites make heavy use of REST and JSON. Dynamically typed languages rule the web and JSON, being simple to parse and produce, is an ideal data exchange protocol for them. Moreover, strongly typed languages such as C++ also have libraries to deal with the data in JSON format.

So, while designing next version of the API our goals were:

• Make JSON first-class output format.
• Build an API based solely on HTTP protocol semantics.
• Pass credentials together with request to avoid separate login calls.
• Allow cross-origin resource sharing (CORS).
• Make calls require only couple lines of code.
• Address certain design shortcomings of SOAP API

Is it hard to use new API? Let’s have a short demo.

Using jQuery? Easy! Create authorization token in application’s setup section, set authtoken variable and let jQuery handle the rest.

var authtoken = "0123456789ABCDEF0123456789ABCDEF";
$.getJSON(
"https://www.teamdesk.net/secure/api/v2/21995/" + authtoken +
"/Test/Default%20View/select.json",
function(data) {
/* here we have data */
}
);

In PHP? Still easy!

$authtoken = "0123456789ABCDEF0123456789ABCDEF";
$data = json_decode(
file_get_contents(
"https://www.teamdesk.net/secure/api/v2/21995/" . $authtoken .
"/Test/Default%20View/select.json"
));

In C#?

string authtoken = "0123456789ABCDEF0123456789ABCDEF";
object data = new JavaScriptSerializer().DeserializeObject(
new WebClient().DownloadString(
"https://www.teamdesk.net/secure/api/v2/21995/" + authtoken +
"/Test/Default%20View/select.json"
));

Please note that simplicity does not mean efficiency. Samples above are dead simple but in order to make API operations more effective you may want to enable compression and caching that will require few extra lines to set up web client properly.

REST API documentation and resources are available here.

Note for SOAP API users

SOAP API is now obsolete. We will maintain it in operational state but we won’t develop it further any longer. When planning upgrade to REST API please consider that while new API’s method names are the same, in many cases they perform differently.

• Select method does not require building SQL-like statements rather receive parameters via URL to query for raw table data. Aggregated results (Min/Max/Sum etc.) can be queried via corresponding view.
• Create, Update and Upsert methods run record change workflow triggers and email notifications by default. In order to disable triggers the user should have Manage Data administrative privilege (this behavior matches record change via UI vs Setup’s Table Import)
• Unlike SOAP API that processes rows in a batch, REST API processes rows to create, update or delete individually – on a way back you’ll receive the status code for each row.
• There is no SetAttachment method – files’ data should be sent together with the rows to create or update.