This article provides a small example of Python script calling XTAM REST API. The example access XTAM REST API to retrieve current user information and XSRF REST API token. Then the example demonstrates the functions to access secret data of a specified record and to create a new record in the specified folder. The article also contains an example of accessing XTAM REST API using API authentication token.
To view XTAM’s full, interactive REST API utilizing the OpenAPI format, navigate to Adminstration > Settings > Application Nodes > API Documentation.
Looking for REST API examples using other scripts? Click PowerShell examples, Shell examples, VBScript examples or Python examples for additional information.
Below is the script demonstrating accessing records secret data and creating a new record. Details of the API calls are outlined in the comments. Note the use of the XSRF token to call data modification functions. The script intention is to illustrate details of the protocol. As a result, the script does not process network errors leaving it to the implementation.
# ------------------------------------------------------------------------------------ # XTAM REST API access script example for Python # # The script will demonstrate the following functions # * to access secret fields of the existing record # * to create a new record # ------------------------------------------------------------------------------------ import requests import json from http.cookies import SimpleCookie # ------------------------------------------------------------------------------------ # Script parameters define XTAM objects used in the script # ------------------------------------------------------------------------------------ # Authentication parameters url = 'https://xtam.company.com/xtam' # XTAM REST API URL login = 'xtam_login' password = 'xtam_password' # XTAM Object IDs and names used in the script rid = 'i-2qhyGh2UB0V' # Record ID to retrieve fid = 'i-2Zh30SUCq7c' # Folder ID to create a new record in tid = 'i-83XfwpNvCHy' # Record Type ID for the new record creation recordName = 'New Record' # Name for the new record recordDescription = 'New record description' # Description of the new record recordCustom = '{"Host":"host", "Port":24, "User":"user", "Password":"password"}' # Custom data for the new record # ------------------------------------------------------------------------------------ # Call to /user/whoami function returns current user data. # In addition, this call returns an REST API token for cross site scripting protection. # ------------------------------------------------------------------------------------ r = requests.get(url + '/rest/user/whoami', auth=(login, password)) user = r.json() # Print user information retrieved from the XTAM server print('Hello ' + user['firstName'] + ' ' + user['lastName']) # Access REST API token for cross-site scripting protection and save it in the xsrf variable cookie = SimpleCookie() cookie.load(r.headers['Set-Cookie']) xsrf = cookie['XSRF-TOKEN'].value #print(xsrf) # ------------------------------------------------------------------------------------ # Example call /record/unlock to retrieve secret data of a record # ------------------------------------------------------------------------------------ r = requests.get(url + '/rest/record/unlock/' + rid, auth=(login, password)) record = r.json() custom = json.loads(record['custom']) print('{0}: {1} ({2}/{3})'.format(record['name'], custom['Host'], custom['User'], custom['Password'])) # ------------------------------------------------------------------------------------ # Example call to /record/new to create a new record # Note that calls that modify XTAM data must include REST API token # ------------------------------------------------------------------------------------ resp = requests.post(url + '/rest/record/new/' + fid + '/' + tid, data={'name':recordName,'description':recordDescription, 'custom':recordCustom}, headers={'Content-Type':'application/x-www-form-urlencoded', 'Accept':'application/json', 'X-XSRF-TOKEN':xsrf}, auth=(login, password)) print(resp) # ------------------------------------------------------------------------------------ # Example call to /folder/create to create a new folder to demonstrate json payload # Note that calls that modify XTAM data must include REST API token # ------------------------------------------------------------------------------------ resp = requests.post(url + '/rest/folder/create/' + fid, json={'name':'Py Folder','description':'Py Description'}, headers={'Content-Type':'application/json', 'Accept':'application/json', 'X-XSRF-TOKEN':xsrf}, auth=(login, password)) print(resp.text)
The next example demonstrates the technique of connecting to XTAM REST API using API authentication tokens. As before, details of the script use are outlined in the comments.
# ------------------------------------------------------------------------------------ # XTAM REST API access script example for Python # # The script will demonstrate API access using API tokens # ------------------------------------------------------------------------------------ import requests import json from http.cookies import SimpleCookie # ------------------------------------------------------------------------------------ # Script parameters define XTAM objects used in the script # ------------------------------------------------------------------------------------ # Authentication parameters url = 'https://xtam.company.com/xtam' # XTAM URL cas = 'https://xtam.company.com/cas' # XTAM Federated Sign-In URL token = 'yourXTAMtoken' # XTAM Token # ------------------------------------------------------------------------------------ # Authentication using the token # ------------------------------------------------------------------------------------ # Exchange REST API Token for a service ticket in Federated Sign-In Service. # Note that a service ticket is short lived so it should be quickly exchanged to more permanent session cookie # Also note disabling of redirects to catch service ticket in the Location header. r = requests.get('{0}/login?service={1}/'.format(cas,url), headers={'token':token}, allow_redirects=False) location = r.headers['Location'] # Exchange service ticket for a session cookie in XTAM. # Save the session cookie to use in consecutive calls r = requests.get(location, allow_redirects=False) jar = r.cookies # ------------------------------------------------------------------------------------ # Call to /user/whoami function returns current user data. # In addition, this call returns an REST API token for cross site scripting protection. # ------------------------------------------------------------------------------------ # Note the use of cookies parameter replacing auth parameter used for basic authentication r = requests.get(url + '/rest/user/whoami', cookies=jar) user = r.json() # Print user information retrieved from the XTAM server print('Hello ' + user['firstName'] + ' ' + user['lastName']) # Access REST API token for cross-site scripting protection and save it in the xsrf variable cookie = SimpleCookie() cookie.load(r.headers['Set-Cookie']) xsrf = cookie['XSRF-TOKEN'].value print('XSRF Token: ' + xsrf)
Out next example demonstrates the technique of connecting to XTAM REST API using user and password when logging in to XTAM server with enabled Federated Sign-In (CAS) component. As before, details of the script use are outlined in the comments.
# ------------------------------------------------------------------------------------ # XTAM REST API access script example for Python # # The script will demonstrate API access using API tokens # ------------------------------------------------------------------------------------ import requests import json from http.cookies import SimpleCookie # ------------------------------------------------------------------------------------ # Script parameters define XTAM objects used in the script # ------------------------------------------------------------------------------------ # Authentication parameters url = 'https://xtam.company.com/xtam' # XTAM URL cas = 'https://xtam.company.com/cas' # XTAM Federated Sign-In URL username = 'XTAM-user-name' # XTAM Account password = 'XTAM-user-password' # XTAM Account Password # ------------------------------------------------------------------------------------ # Authentication using user / password for Federated Sign-In component # ------------------------------------------------------------------------------------ # Get TGT ticket granting ticket from user and password. # Note that a TGT ticket is short lived so it should be quickly exchanged to more permanent session cookie # Also note disabling of redirects to catch service ticket in the Location header. r = requests.post('{0}/v1/tickets'.format(cas), data={'username':username,'password':password}, headers={'Content-Type':'application/x-www-form-urlencoded'}, allow_redirects=False) location = r.headers['Location'] # get service ticket (ST) from TGT. r = requests.post(location, data={'service':'{0}/'.format(url)}, allow_redirects=False) st=r.text # Exchange service ticket for a session cookie in XTAM. # Save the session cookie to use in consecutive calls r = requests.get(location, allow_redirects=False) jar = r.cookies # ------------------------------------------------------------------------------------ # Call to /user/whoami function returns current user data. # In addition, this call returns an REST API token for cross site scripting protection. # ------------------------------------------------------------------------------------ # Note the use of cookies parameter replacing auth parameter used for basic authentication r = requests.get(url + '/rest/user/whoami', cookies=jar) user = r.json() # Print user information retrieved from the XTAM server print('Hello ' + user['firstName'] + ' ' + user['lastName']) # Access REST API token for cross-site scripting protection and save it in the xsrf variable cookie = SimpleCookie() cookie.load(r.headers['Set-Cookie']) xsrf = cookie['XSRF-TOKEN'].value print('XSRF Token: ' + xsrf)
