Skip to main content

TDS XML API

This document outlines the XML-API to communicate with TDS. The XML-API allows you to write custom programs that work with the template or inspection data stored by TDS.

warning

TDS XML parsing does not support XML comments in the form of

<myTag>
  <!-- a comment to my value below -->
  <myValue>25</myValue> <!-- or an inline comment -->
</myTag>

Authenticating against TDS​

TDS uses an authentication token combined with the HTTP basic-auth protocol. After you have successfully authenticated against TDS, the server will send you an auth token as part of the HTTP response. That auth token must be present in each HTTP request sent to the API.

To request a token call POST/users/get_token. The token must be set within the headers subsequent HTTP requests:

Authorization: Token: ${AUTH-TOKEN}
info

Note that all endpoints below that require may additionally return:

  • 401: Unauthorized in case of missing authentication
  • 403: Forbidden in case of missing privileges
  • 301: Redirect to redirect to the login screen

The latter will only happen when calling user facing endpoints (anything under /view) which redirect to the login screen.

Finally, all endpoints may return 500: Internal Server Error in case of unextected input errors or database issues.

Common Use-cases​

Here some examples for common use-cases of the API.

Example: Query all new inspections​

A common use-case is to have a scheduled task query TDS for new inspections. This can be done by providing the timestamp of the most recent, knwon inspection and querying all inspections since after that.

E.g., given the most recent inspection that has been returned by my last query was on 2024-10-10 15:22:14, the respecitve next query would look like this:

https://tds.example.com/inspections?limit=-1&uploaded-date-start=2024-10-10 15:22:14

Using the API with CURL​

To authenticate against TDS and obtain a user token, the following CURL command can be executed.

curl -X POST --insecure -H "Content-Type: application/x-www-form-urlencoded" -d 'User[login]=<your-username>' -d 'User[password]=<your-password>' https://<your-tds-address>/users/get_token

Just replace <your-username>, <your-password> and <your-tds-address> respectively.

To request any of the endpoints - the parts catalogue in this example - provide the obtained user token and execute the following command.

curl -X GET --insecure -H "Authorization: Token: <your-token>" https://<your-tds-address>/parts/all

Just replace <your-token> with the obtained user token.

To post to any of the endpoints - and add a new part in this example - create the appropriate XML-document and send it to the respective endpoint.

curl -X POST --insecure -H "Authorization: Token: <your-token>" -T <your-xml-file> https://<your-tds-address>/parts

Just replace <your-token> with the user token, <your-xml-file> with the path to the prepared xml body and <your-tds-address> with the address to your TDS server.

Authenticating and querying using Python​

The following Python code snippet authenticates against a TDS instance (<your-tds-address>) with <your-username> and <your-password>, downloads a specific inspection report (inspection with id 1 in this case) and print all the contents of that inspection.

This snippet relies on the 3rd party requests library which can be installed with pip install requests.

import requests
import xml.etree.ElementTree as ET

TdsAddress = "https://<your-tds-address>"
InspectionID = "1" ## Or any other inspection you want to download

User = "<your-username>"
Pass = "<your-password>"

## Get the authentication token
tokenXml = requests.post(
    f"{TdsAddress}/users/get_token",
    verify=False,
    headers={"Content-type": "application/x-www-form-urlencoded"},
    data=f"User[login]={User}&User[password]={Pass}",
)
token = ET.fromstring(tokenXml.text).text

## Get all inspections
## inspectionsXml = requests.get(f"{TdsAddress}/inspections")

## Get a single inspection
inspectionXml = requests.get(
    f"{TdsAddress}/inspections/{InspectionID}",
    verify=False,
    headers={"Authorization": f"Token: {token}"},
)
inspectionTree = ET.XML(inspectionXml.text)

for child in inspectionTree:
    print("Inspection:")
    for item in child:
        print(f"{item.tag}: {item.text}")

A full example to upload a part with a couple of welds, images and a route is provided here: Full Part Import Example