AJAX API for TelHosting Software

This reference describes the new JavaScript-format AJAX interface that the TelHosting Software exports. The web interface for the .tel control pane uses the same API.

This interface closely follows the web interface layout, and is divided into the following groups of functions:

• Login - logging into the TelHosting Software system
• Wizard - preferences
• Settings - password and related settings
• Zone management - checking zones for domains
• Folder management - subdomains
• Profile management - profiles and associated records
• Text header management - TXT record contents
• Node information management - NINFO records for status
• Location management - LOC record contents
• Record management - NAPTR (naming authority pointer) record(s) content
• AdSense management - Google AdSense advertising blocks
• Group management - groups of readers for privacy settings
• Keyword management - keywords for search indexing
• Export / import - operations to store/retrieve a copy of the data in XML
• Design - operations to adjust colour and other display settings for the proxy

The document assumes that the reader is familiar with basics of the .tel technology. For introductory materials, please read the whitepapers.

Method call format

To call a method from this interface, use the namespace for the method's group and the method itself, e.g.:

/g2/json/domain/record/gettextheader.action - This calls method gettextheader to retrieve the TXT record for the given domain.

Login

The namespace for this group is: namespace=/g2/json/

login (inputLogin, processResult, processError)

/**
 * this method is used to login a user;
 * depending on the type of user logging in, a URL is returned, which can
 * be used by the dashboard to forward the user;
 * the flag usedTempPassword tells, whether the user is logging in with
 * a temporary password; in this case, the user should prompted to change
 * his password immediately, since he won't be able to log in using this
 * password another time
 */

inputPreferences = {
	userName: "johnsmith",
	password: "secret"
};

successResult = {
	success: true,
	usedTempPassword: false,
	urlForward: "localhost:8080/ps-server/g2/dashboard.action",
	actionMessages: ["user logged in successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["invalid user name or password",
               	       "more errors here..."]
}; 

validation: login (inputLogin, processResult, processError)

For security reasons, any errors in the combination of username and password or a non existing username will lead to the same error.

logout (null, processResult, processError)

/**
 * this method is used to logout a user
 */

/** no input needed */

successResult = {
	success: true,
	actionMessages: ["user logged out successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["an unexecpted problem occurred",
               	       "more errors here..."]
}; 

validation: logout (null, processResult, processError)

no validation required as the method does not have any input values

passwordRetrieval (inputLogin, processResult, processError)

/**
 * this method allows the user to reset his password; a valid
 * e-mail address has to be supplied and an an e-mail is sent to this
 * containing new temporary passwords for every user having this
 * address
 */

inputLogin = {
	email: "johnsmith@smith.th"
};

successResult = {
	actionMessages: ["e-mail sent",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["e-mail address does not exist",
               	       "more errors here..."]
}; 

validation: passwordRetrieval (inputLogin, processResult, processError)

the input is not validated

Wizard

The namespace for this group is: namespace=/g2/json/preferences

setDashboardPreferences (inputPreferences, processResult, processError)

/**
 * this method sets the four flags for the dashboard preferences; these
 * preferences can be different for each second-level domain
 */

inputPreferences = {
	domainName: "cartman.tel",
	enablePrivacy: true,
	enableProfiles: false,
	enableFolders: true,
	displayFriending: true
};

successResult = {
	success: true,
	actionMessages: ["preferences successfully set",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot set preferences",
               	       "more errors here..."]
}; 

getDashboardPreferences (null, processResult, processError)

/**
 * this method returns the four flags for the dashboard preferences
 * of the given (second-level) domain; if a subdomain is submitted, the
 * preferences of its second-level domain are returned
 */

inputPreferences = {
	domainName: "cartman.tel"
};


successResult = {
	success: true,
	enablePrivacy: true,
	enableProfiles: false,
	enableFolders: true,
	displayFriending: true
	actionMessages: ["request successful",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get preferences",
               	       "more errors here..."]
}; 

Settings

The namespace for this group is: namespace=/g2/json/settings

changePassword (inputPassword, processResult, processError)

/**
 * method to change the user's password
 */

inputPassword = {
	newPassword: "secret"
};

successResult = {
	success: true,
	actionMessages: ["password changed successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change password",
               	       "more errors here..."],
	fieldErrors: ["newPassword", "invalid password"]
};

validation: changePassword (inputPassword, processResult, processError)

getEmail (null, processResult, processError)

/**
 * method to obtain the user's e-mail address
 */

/** no input needed */

successResult = {
	success: true,
	email: john@smith.org,
	actionMessages: ["email obtained successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
};

errorResult = {
	success: false,
	actionErrors: ["cannot obtain email",
               	       "more errors here..."]
};

changeEmail (inputEmail, processResult, processError)

/**
 * method to change the user's e-mail address
 */

inputEmail = {
	newEmail: "tel@telinc.nic"
};

successResult = {
	success: true,
	actionMessages: ["email changed successfully",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change email",
               	       "more errors here..."],
	fieldErrors: ["email", "invalid password"]
};

validation: changeEmail (inputEmail, processResult, processError)

clearRecentLocations (null, processResult, processError)

/**
 * method to reset the recent location strings
 */

/** no input needed */

successResult = {
	success: true,
	actionMessages: ["recent location list cleared",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot clear recent location list",
               	       "more errors here..."]
};

validation: clearRecentLocations (null, processResult, processError)

no validation required as method has no input values

setLocalLanguage (input, processresult, processerror)

/**
 * set the user's local language, tries to rename some objects (the
 * default profile, the "all friends" group) of the given domain, thus
 * should be called upon initial loading of the dashboard and upon
 * domain change;
 * renaming only occurs if the current name is the name of the object in
 * a supported language (different from the requested one, of course);
 * if the locallanguage parameter is omitted, the browser's
 * language is used as fallback
 * errors occurring during renaming (because an object of the same name
 * already exists) are reported but do not lead to abortion of the
 * operation, i.e. other objects may have been renamed anyway;
 * the returned actionmessages can be used to differentiate between
 * success without any renaming done and success with at least one
 * object name change (s. examples below)
 */

input = {
	domainName: "cartman.tel",
	localLanguage: "de"
};

successresult = {
	success: true,
	actionmessages: ["default object names successfully updated with local language.",
			 "default object names do not need to be updated.",
			 "3rd message here"]
}; 

errorresult = {
	success: false,
	actionerrors: ["please specify a domain name.",
		       "more errors here..."]
};

validation: setLocalLanguage (input, processresult, processerror)

getProxySettings (inputFolder, processResult, processError)

/**
 * method to obtain the domain's proxy settings;
 * the searchConfiguration can be one of the following three value
 * - SearchAll: all .tel domains will be searched
 * - SearchThis: only this .tel domain (incl. all super and sub domains) will be searched
 * - NoSearch: search is deactivated, no search field will be displayed
 * furthermore the returned data says whether the "Manage .tel" link and the link to Telnic
 * will be displayed or not
 */

inputFolder = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	searchConfiguration: "SearchAll",
	showManageLink: false,
	showTelnicLink: true,
	actionMessages: [""]
};

errorResult = {
	success: false,
	actionErrors: ["cannot obtain proxy settings",
               	       "more errors here..."]
};

validation: getProxySettings (inputFolder, processResult, processError)

changeProxySettings (inputSettings, processResult, processError)

/**
 * method to change the domain's proxy settings;
 * the searchConfiguration can take one of the following three value
 * - SearchAll: all .tel domains will be searched
 * - SearchThis: only this .tel domain (incl. all super and sub domains) will be searched
 * - NoSearch: search is deactivated, no search field will be displayed
 * furthermore the user can define whether the "Manage .tel" link and the link to Telnic
 * should be displayed or not
 */

inputSettings = {
	domainName: "cartman.tel",
	searchConfiguration: "NoSearch",
	showManageLink: false,
	showTelnicLink: true
};

successResult = {
	success: true,
	actionMessages: ["Settings updated."]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot change proxy setting",
               	       "more errors here..."]
};

validation: changeProxySettings (inputSettings, processResult, processError)

Zone management

checkZone (zone, processResult, processError)

/**
 * this method returns information about the existence of a zone with the given name;
 * it may be called to give the user a visual indication regarding whether the zone
 * for the domain he's looking at exists (i.e., whether the domain is "active" and
 * published in DNS); in case of a successful call, the "exists" property of the
 * successResult contains true if the zone exists and false otherwise
 */

zone = {
	zoneName: "cartman.tel"
};

successResult = {
        success: true,
        actionMessages: ["Zone checked successfully."],
        exists: true
};

errorResult = {
        success: false,
        actionErrors: ["some error",
		       "more errors here..."]
};

validation: be_checkZone (zone, processResult, processError)

Folder management

The namespace for this group is: namespace=/g2/json/domain/

getSubFolderList (inputFolder, processResult, processError)

/** 
 * retrieve the list of subfolders for the given folder (i.e. domain) name;
 * if the domainName is "tel", a list of all folders of the current user is
 * returned;
 * the input domain name is never returned, so the resulting list may be empty
 * the boolean parameter recursive determines whether all subdomains are
 * returned (true) or only the direct subdomains (false)
 */


input = {
	domainName: "tel",  /** gets a list of all folders */
	recursive: true
};

successResult = {
	success: true,
	folderList: [{id: 12, name: "cartman.tel", soConnection: "Active"},
		     {id: 23, name: "stan.cartman.tel", soConnection: "Uninitialised"},
		     {id: 14, name: "henry.tel", soConnection: "Incomplete"}],
	actionMessages: ["request successful",


                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get folder list",
               	       "more errors here..."]
}; 

validation: getSubFolderList (inputFolder, processResult, processError)

storeFolder (inputFolder, processResult, processError)

/** 
 * add a new folder;
 * the complete domain name of the new folder has to be provided;
 * the id of the new folder will be supplied in case of success 
 */

inputFolder = {
	domainName: "stan.cartman.tel"
};

successResult = {
	success: true,
	domainId: 25,
	actionMessages: ["folder added",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot add folder",
               	       "more errors here..."],
	fieldErrors: ["domainName", "invalid domain name"]
}; 

validation: storeFolder (inputFolder, processResult, processError)

renameFolder (inputFolder, processResult, processError)

/** 
 * rename a folder;
 * the complete domain name of the old and new folder name has to be provided;
 * the id of the new folder will stay the same; both domain names must be a
 * direct sub-domain of the same domain and they may not be apex domains;
 * all sub-domains of the domain to be renamed are renamed as well; furthermore
 * all non-terminal NAPTRs (domain links) of the current user are checked if they
 * point to the old domain name or one of its sub-domains, if so the NAPTRs will be
 * renamed accordingly; all other domain properties (records, profiles, groups,
 * etc.) remain as they are;
 */

inputFolder = {
	domainName: "stan.cartman.tel"
	newDomainName: "john.cartman.tel"
};

successResult = {
	success: true,
	actionMessages: ["folder renamed",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot rename folder",
               	       "more errors here..."],
	fieldErrors: ["newDomainName", "invalid domain name"]
}; 

validation: renameFolder (inputFolder, processResult, processError)

deleteFolder (inputFolder, processResult, processError)

/** 
 * delete a folder;
* the complete domain name of the folder has to be provided; the folder
* including all subdomains will be deleted; the folder must not be a
* root domain
 */

inputFolder = {
	domainName: "test.cartman.tel"
};

successResult = {
	success: true,
	actionMessages: ["folder deleted"
			 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot delete root domain",
               	       "more errors here..."]
}; 

validation: deleteFolder (inputFolder, processResult, processError)

setDisplayString (inputFolder, processResult, processError)

/** 
 * set the domain display string for this domain; if the display string is
 * missing or set to the empty string, the domain display string is removed
 */

inputFolder = {
	domainName: "stan.cartman.tel",
	displayString "Stan Cartman: My domain"
};

successResult = {
	success: true,
	actionMessages: ["domain display string set",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot set domain display string",
               	       "more errors here..."],
	fieldErrors: ["newDomainName", "invalid domain name"]
}; 

validation: setDisplayString (inputFolder, processResult, processError)

getDisplayString (inputFolder, processResult, processError)

/** 
 * get the domain display string for this domain; if the display string is
 * not set the method returns null as the display string
 */

inputFolder = {
	domainName: "stan.cartman.tel"
};

successResult = {
	success: true,
	displayString: "Stan's domain",
	actionMessages: ["domain display string retrieved",
                     	 "2nd message here",
                     	 "3rd message here"]
}; 

errorResult = {
	success: false,
	actionErrors: ["cannot get domain display string",
               	       "more errors here..."],
	fieldErrors: ["newDomainName", "invalid domain name"]
}; 

validation: getDisplayString (inputFolder, processResult, processError)

getExpireInfo (domainName, processResult, processError)

/**
* get expire information for domainName
*
* returns "This domain is due to expire on ..." if domain expires within the next 30 days
* returns "This domain expired ..." if domain expired within the last 45 days
* returns null in any other case
*/
domainName = {
domainName: "cartman.tel"
};
successResult = {
success: true,
date : null,
actionMessages: null,
displayString: "This domain is due to expire on Tuesday 23 Mar 2010 27 2332800000!. To avoid losing this name please contact your domain provider and request a renewal."
};

validation: getExpireInfo (domainName, processResult, processError)

Profile management

The namespace for this group is: namespace=/g2/json/domain/profile

getProfileList (inputProfile, processResult, processError)

/** 
 * retrieve the list of profiles for the specified domain;
 * the successResult contains the profileList, consisting of id and name
 * of the profile as well as flags whether it is the default and/or
 * active profile and a list of ids of the records belonging to this
 * profile;
 * an optional parameter simpleVersion may be added; if missing it is set
 * to false with no change; if set to true, the request will not return
 * the recordIds, this list will always be null;
 */

inputProfile = {
	domainName: "cartman.tel"
};

successResult = {
	success: true,
	profileList: [{id: 12, name