TeamDynamix API/Web Services Overview

Summary

This article is intended to provide instructions for how to access the TeamDynamix API/Web Services documentation and other general API-related information. It is not intended to describe how to use, call or otherwise explain this documentation.

How do I access the API/Web Services documentation?

TeamDynamix RESTful Web API Documentation

The TeamDynamix RESTful Web API information is located below. For SaaS customers, replace yourTeamDynamixDomain with your actual TeamDynamix domain (eg: myschool.teamdynamix.com) to view the documentation.

• SaaS Production: https://yourTeamDynamixDomain/TDWebAPI/
• SaaS Sandbox: https://yourTeamDynamixDomain/SBTDWebAPI/
• Installed Environments: https://yourTeamDynamixDomainAndPath/TDWebAPI/

These are the preferred APIs to use and will be continuously maintained and expanded going forwards.

Usage

When using the API, you should access it using your school's TeamDynamix domain substituted in place of yourTeamDynamixDomain. The URLs below work on the example where a school's TeamDynamix domain is abcuniversity.teamdynamix.com.

Production API Access

The production API URL will be abcuniversity.teamdynamix.com/TDWebApi/ when making API calls. The /TDWebApi/ in the URL is what signifies production (no SB prefix before TDWebApi).

Sandbox API Access

The sandbox API URL will be abcuniversity.teamdynamix.com/SBTDWebApi/ when making API calls. The /SBTDWebApi/ in the URL is what signifies sandbox (a SB prefix before TDWebApi).

Request Size Limits

The RESTful Web API has a global 4MB request size limit. This impacts all requests. Examples of scenarios which might be impacted (non-exhaustive list):

1. Requests with file attachments
2. POST / PUT / PATCH Requests with large JSON bodies

Again, any request exceeding 4MB in size will be rejected. If this impacts your API usage you may need to investigate the following workarounds:

• Compress/zip file attachments being sent as attachments. Or, in addition to compression, chunk the files into multiple archive files.
• Split up POST / PUT / PATCH requests into additional, smaller calls to achieve the same result.
• If a large JSON body is happening due to a single large description/comment for an item, consider attaching that description/comment as a file attachment instead. You could then compress that file attachment before uploading.

Data Type References

The API documentation will generally refer to data types of objects and values throughout the API in terms of .NET Framework data types. Occasionally there will be more specific instructions about JSON-specific formatting and data types, such as how to format dates/content type headers/etc., but the data type references are all .NET data types outside of those exceptions. This because the API is written in .NET and the .NET data type references will align 1:1 if used with the TeamDynamix API .DLL helper objects (available from the TDNext Downloads app). These are objects that can be directly included in client-side .NET applications working with the API to provide easy object property bags instead of having to create your own or using anonymous objects.

One of the more common questions is around references to IEnumerables, Lists, Collections, Dictionaries and Arrays. All of these will end up equating to a JSON array of some sort. Depending on what the internal type of the IEnumerable/List/Collection/Dictionary/Array is, the items contained inside of the JSON array will either be JSON primitive data types, JSON objects or JSON arrays. For instance, an IEnumerable(Of Int32) would simply mean a JSON array of integers. An IEnumerable(Of [TeamDynamix API object]) however, would be a JSON array of JSON objects representing the TeamDynamix API object in question.

CORS / Client-Side Scripting Support

CORS support for client-side scripting is enabled in the TeamDynamix REST API except for the following endpoints (and their sandbox equivalents):

• POST /TDWebApi/api/auth/loginadmin
• POST /TDWebApi/api/auth/loginsso

Essentially, client-side scripting cannot be used to obtain the special admin token for endpoints which require an admin token for authorization. All other user login and non-admin endpoint usage is 100% supported.

Single Sign On (SSO) Support 

The API has no support for Single Sign On (SSO) authentication for any automated scripting processes. You must use a non-SSO TeamDynamix User-typed account, service account or admin service account to authenticate.

The POST /TDWebApi/api/auth/loginsso endpoint is only really meant for internal TeamDynamix usage in TeamDynamix client-side javascript code. It is not a method for authenticating into the API from external scripting solutions.