Command Test (ZoneEdit.com)

Integration & Routing Specifications

Definitions

For purposes of this documentation 'partner' refers to the integration partner and 'client' refers to a client using the DNS editor.

It is essential that your system be XML compliant, it must ignore unknown tags and attributes returned by the API, and must not depend on the order of the attributes, or tags returned.

Advanced Integration

Integration partners can configure and link to ZoneEdit.Com in a seamless and secure way using integrated administration and/or encrypted routing.

1. Integrated Administration : used to create new users and assign zones to users. This technique is required if ZoneEdit is providing "Zone Navigation" for the user.

2. Encrypted routing : used to send clients directly to the private-labeled site - that have been pre-authenticated by the partner's server.

Both techniques above : Complete site integration, with low code maintenance can be achieved by combining these techniques.

3. Record Editor API : used to modify records directly for your users. If you need to rewrite the GUI, or have another GUI to integrate with - use this method. You will have to maintain upward compatiblity with the API, as new versions are released.

PERL Module : Prewritten compliance with the API for PERL users can be gotten here It is not necessary to use PERL, and our API has no perl-specific features or functions.

Example using PERL to do Integration

    use ZoneEdit;

    # admin user set aside for this API
    $ZoneEdit::USERNAME = 'username';
    $ZoneEdit::PASSWORD = 'password';

    # create a user called fred
    print ZoneEdit::add_user('fred', 'pass556hy');

    # adds 'atreju.com' to fred's zones
    print ZoneEdit::add_user_zone('fred', 'atreju.com');

    # creates a pre-authenticated link for fred
    print ZoneEdit::create_link('fred', 'atreju.com', 'VIEW');

    # deletes fred
    print ZoneEdit::del_user('fred');

Example using Cold Fusion to add a record.

<cfhttp url="https://api.zoneedit.com/auth/admin/command.html"
		method="POST"
		port="443"
		username="adminusername"
		password="adminpassword"
		throwonerror="yes">

 <cfhttpparam name="user" type="FORMFIELD" value="nameofuser">
 <cfhttpparam name="zone" type="FORMFIELD" value="apitest.com">
 <cfhttpparam name="command" type="FORMFIELD" value="addrecord">
 <cfhttpparam name="type" type="FORMFIELD" value="A">
 <cfhttpparam name="dnsfrom" type="FORMFIELD" value="www">
 <cfhttpparam name="dnsto" type="FORMFIELD" value="1.2.3.4">

</cfhttp>

1. Integrated Administration

If you want clients to view a list of zones... or you require increased security, or you are NOT planning on implementing encrypted routing, then you must maintain a list of users and zones on the ZoneEdit server. Normally, this list is maintained manually using the Site Administration GUI. However, there may be certain situations where you may want to automatically ADD a user or user/zone to the ZoneEdit server's database.

Technique:

The partner initiates an SSL form-url-encoded request to the ZoneEdit server (https://api.zoneedit.com/auth/admin/command.html)
The partner POSTS the complete administration command to the ZoneEdit server using his 'partner username' and 'partner password'.
The ZoneEdit server responds with an XML formatted response (CAN BE FOUND HERE).
The partner VERIFIES the response, and should be careful to take action if the response is invalid or unexpected.

1a. Sending the command

The administration command is a "&" delimited string of name=value pairs transmitted via SSL to the ZoneEdit server.

Command names are case-insensitive

An example command for adding a user and adding a zone for that user is: command=adduserzone&user=erik&zone=bigdawg.com

1b. Command & Specifications

AddUser	Adds or Edits a user to the database.
AddUserZone	Edits a user in the database and grants permission to edit a zone.
EditUserZone	Edits a zone's parameters and permissions.
DelUser	Deletes a user.
DelUserZone	Deletes a zone from a user's account.

See section 3 below for more info on parameters.

1c. Reading the response

The response to the administrative request is a simple XML formatted set of information. The TAGS and ATTRIBUTES contain all of the necessary information about the response. The content strings are merely 'suggested error information', and MUST NOT be used for decision making.

XML Tags & Attributes:

Example of a successful response:

<ze><response>
        <success code=200>The AddUser request completed successfully</success>
        <warning code=301>The user was already in the database</warning>
</response></ze>

Example of a failed response:

<ze><response>
        <failure code=500>The command 'adduferzone' was not recognized</failure>
        <failure code=501>The user parameter was empty</failure>
</response></ze>

As you can see, you can use ANY language to post the correct arguments tot he command page. Languages with XML support will make parsing the results a lot easier.

2. Encrypted Routing

If your clients are already logging in to your server, you can send a preauthenticated routing command to the ZoneEdit server that tells it to allow the client to login without supplying a password.

The partner is issued a hexadecimal 'secret' key (this must be generated by using the partner integration page).
The partner programs ZoneEdit integration into his site.
The client requests a web page from the partner that has links to the ZoneEdit site.
Using ASP/Perl/JSP or other technologies, the partner encrypts the routing command using this secret key (decoded from hex to binary), and places it in a hidden form field on his web page.
The form points to an SSL URL on the ZoneEdit server.
The client clicks on a "submit" button for the form.
The ZoneEdit server issues a temporary session key to the client and routes him to the requested page.

2a. Encrypting the command

The routing command is a FORM-URL-ENCODED string ENCRYPTED using Blowfish and encoded as a case-insensitive HEX string.

The routing command must be POSTED to the ZoneEdit server using SSL from the PARTNER's web site.

The following is an example of a base-64 encoded routing command that was encrypted with the Blowfish algorithm using the word "secret" as a password. (An image can be used instead of the HTML submit button.)

The original string was: user=erik&type=WIZ&zone=default

<FORM ACTION="https://www.zoneedit.com/auth/admin/command.html" METHOD=POST>
<INPUT TYPE=HIDDEN NAME=route1
 VALUE="/nq/2ZiziJ5LJ0Hxh62S0N8xvwH/ohoLV+i90OfJ1UKqr4ZjX2lDFkBGEebUCGt1">
<INPUT TYPE=SUBMIT NAME=submit1 VALUE="Edit Defaults">
</FORM>

2b. Routing Command Parameters

Each routing command must have a user, zone, and a type. Routing keys expire in 1 hour. See section 3 below for more info.

3. Record Editor Commands

See section 1a. and 1c. for the technique used to send the commands and read the responses.

All commands require the "type" and the "zone". Optional parameters include dnsfrom, dnsto, forward and rank, and are type-specific. For example:

command=addrecord&type=A&dnsfrom=www&dnsto=1.2.3.4

It is essential that your system be XML compliant, it must ignore of unknown tags and attributes returned by the API, and must not depend on the order of the attributes, or tags returned.

3a. Record Edit Commands:

AddRecord : Adds a record.
DelRecord : Deletes a record. You must identify which record by using the dnsfrom/dnsto/forward parameters or the record 'id' returned by the "view" command.
ViewRecord : Displays records. If the type is not specified, it shows all records.
ChangeRecord : Changes a record.

3b. Record Edit Types:

type=A : IP Address record. 'dnsfrom' is the subdomain (optional). 'dnsto' is the ip address.
type=MX : MX record. 'dnsfrom' is the subdomain (optional). 'dnsto' is the mail server domain name. 'rank' is the numeric rank.
type=MF : Mail Forward. 'dnsto' is the forwarded address. 'forward' is the destination address.
type=WF : Web Forward. 'dnsfrom' is the subdomain (optional). 'forward' is the destination URL.
type=WP : Web Park. 'dnsfrom' is the subdomain (optional). 'dnsto' is the name of the parked page.
type=PTR : Reverse DNS. 'dnsfrom' is the arpa subdomain. 'dnsto' is the domain name.
type=META : Meta Tags. 'txt', 'title', 'metadesc', 'metakey' are the fields. Only works with ChangeRecord.

3c. Other Commands:

AddUserCredit: Adds a credit to the users account. Required parameters: "user, credits-amount". Optional parameters: "credits-paid, credits-comment".

4. Parameter Specifications

User:

A unique logon name is required. This uniquely identifies the user accessing the ZoneEdit server.

Zone:

The domain name that is being routed to must be supplied. The special zone 'default' may be used to route the user to the zone defaults and account settings area.

Type:

For Routing - specifies which type of editing screen will be shown to the user, or the type of the record.

MX	MX-record screen
A	A-record screen
CNAME	CNAME-record screen
SOA	SOA-record screen
MF	Mail Forward screen
WF	Web Forward screen
VIEW	VIEW screen (default)

For Record Edits - specifies which type of record to edit.

Shadow:

For add/change record commands only - specifies "cloaking" for webforwards. (0 = default, 1 = cloaked)

TTL:

For AddUserZone - the SOA TTL, for A/CNAME/MX records, the "per-record" TTL.

Refresh, Retry, Expires:

For AddUserZone only: SOA parameters.

Slave, MasterIP:

For turning on/turning off slave zones: Slave=1 or =0, MasterIP=

TeamID:

Optional, for reseller's who have sub-resellers to be able to execute command on behalf of their client's users.

Zone Flags:

AddUserZone, EditUserZone both support the following flags, which can have a 0 or 1 value: caneditdns, hasbackupmx, canwebforward, canmailforward, canwebpark

Partners can use our html translation engine to reformat the toolbar, or eliminate it altogether, replacing it with API routing function access.