nl.ae Webmaster API - integrate our service into your site using PHP
Are you an experienced PHPer and do you want to integrate our service smoothly into your PHP scripts? Look no further, our API has been made exactly for that. By using our API you can easily improve your site by adding another service or feature: free domain names. Below are some howto and script examples of how to use our API in your PHP scripts. We also recommend you to carefully examine the complete example script at the bottom of the page after reading all steps. Use of this API is completely free of charge.
What can I do with it?
Since we give you all the code there are a lot of possibilities and things you can do with our API. We will however give some examples to give you a general idea. If you run a free forum service for example you could integrate our service to (automatically) give every forum a short domain name. Or, you could give every member of your site his own profile domain. There are a lot more ideas we can think of, just be imaginative!
Step 0/4
This is an optional step used only when you want to check a domain's availability before doing anything else. By using this step you can first check whether a domain is available and only enter other information after you know it's available. You can enter the domain using the $_GET attribute, for example:
<?php
$domain = $_POST['domain'];
$whois = file_get_contents("http://nl.ae/domainapi/whois.php?domain=".$domain);
If ($whois) { //1 equals true
echo "Domain is available for registration.";
}
Else {
echo "Domain is not available for registration (invalid, banned or taken).";
}
?>
$whois will return 1 when $domain is available and 0 otherwise.
Step 1/4
To avoid bots (automated scripts) it is required to use our CAPTCHA when integrating our service to your site. To do so you first have to authenticate with our free domain server by receiving a unique identifier. You can receive a unique identifier by placing the following at the top of your code, note that you must have started sessions using session_start(); first if you haven't done so yet:
<?php
session_start(); //only needed if you haven't done so yet at the top of your script!
$_SESSION['apiid'] = file_get_contents("http://nl.ae/domainapi/reqid.php");
?>
The CAPTCHA will look like this:
Step 2/4
Now show our CAPTCHA using the received ID and place it into your form. You can do so by giving the ID as a $_GET attribute:
<p><label for="verification">Anti-Bot Verification</label>
<img src="http://nl.ae/domainapi/captcha.php?id=<?php echo $_SESSION['apiid']; ?>" />
<input id="verification" name="verification" type="text" maxlength="6" value="" /><br /></p>
Step 3/4
Now send the inputfields after checking the values to our server using a method like:
<?php
$domapi = file_get_contents("http://nl.ae/domainapi/register.php?id=".$_SESSION['apiid']."&captcha=".$_POST['captcha']."&domain=".$_POST['domain']."&url=".$_POST['url']."&email=".$_POST['email']."&category=".$_POST['category']."&title=".$_POST['title']."&description=".$_POST['description']."&keywords=".$_POST['keywords']."&favicon=".$_POST['favicon']."&language=".$_POST['language']."&revisit=".$_POST['revisit']."&robots=".$_POST['robots']);
?>
Step 4/4
The result of your request is now stored in $domapi - your script must now decide what to do with that return value. These are the possibilities:
| Value | Description |
| 1 | Success: domain has been registered and an e-mail has been send to the user. The user will have to login using the information found in the mail at www.login.nl.ae to activate the domain. |
| 0 | Error: no ID has been entered (you forgot to insert the ID $_GET attribute in your script). |
| -1 | Error: no CAPTCHA has been entered (ask user to re-enter a new captcha with a new ID). |
| -2 | Error: CAPTCHA does not match id (ask user to re-enter a new captcha with a new ID). |
| -3 | Error: domain is invalid or empty (domains can not have illegal characters, less then 2 characters or more then 50 characters). |
| -4 | Error: domain is taken or banned (ask user to choose an other domain). |
| -5 | Error: url is invalid, banned or empty (url must start with http://, https://, callto://, callto:, mailto://, mailto: or irc:// and must have less then 2048 characters). |
| -6 | Error: email address is invalid or empty (ask user to re-enter a valid one). |
| -7 | Error: category is invalid or empty (category MUST be exact to one of the following: business, education, computers, games, health, teen, miscelaneous, blogs, religion, science, society, sport, literature, multimedia, entertainement). |
| -8 | Error: invalid title value (must have 2 or more characters and less then 100 characters), this value is optional. |
| -9 | Error: invalid description value (may not have more then 150 characters), this value is optional. |
| -10 | Error: invalid keywords value (may not have more then 380 characters), this value is optional. |
| -11 | Error: invalid favicon path (must end with .ico and start with http:// or https://, may not have more then 500 characters), this value is optional. |
| -12 | Error: invalid language value (may not have more then 50 characters), this value is optional. |
| -13 | Error: invalid revisit value (must be a number higher then 3 and lower then 999, enter 0 or empty to let search engines decide (recommended)), this value is optional. |
| -14 | Error: invalid robots (may not have more then 50 characters), this value is optional. |
Note that you have to request a new identifier (step 1) and captcha (step 2) when you have received an invalid result. A very simple example of your script reacting to the return value:
<?php
If ($domapi == 1) {
$error = 0;
$message = "Congratulations, your domain has been registered. Check your e-mail to activate it!";
}
Else {
$_SESSION['apiid'] = file_get_contents("http://nl.ae/domainapi/reqid.php");
$error = 1;
$message = "This domain is unavailable or an error has occured, please check your input!";
}
?>
Check the below complete example script for a more detailed script and API reaction on all possible return values.
Complete script example (Live Demo)
This example script can register nl.ae free domain names using the API, please read the comments for detailed information.
<?php
//start sessions
session_start();
//there are 3 phases in this script: domain check phase (1), input phase (2) and finish phase (3) - if no phase set, set phase to 1
If (!isset($_SESSION['phase'])) {
$_SESSION['phase'] = 1;
}
//if form has been submitted and phase = 1
If (($_SERVER['REQUEST_METHOD']=='POST') AND ($_SESSION['phase'] == 1)) {
$_SESSION['domain'] = $_POST['domain']; //get posted value
$send = 1; //form has been send
$whois = file_get_contents("http://nl.ae/domainapi/whois.php?domain=".$_SESSION['domain']); //check whether the domain is available, returns 1 or 0
If ($whois) { //$whois is 1, so the domain is still available, go to phase 2 to let user fill in details
$_SESSION['phase'] = 2;
}
ElseIf ($whois == 0) { //the domain is unavailable for registration
$domain_error = "Sorry, ".$_SESSION['domain'].".nl.ae is unavailable for registration, please choose an other domain.";
}
Else { //this should not happen - maybe your server is running PHP on safe mode (or file_get_contents is otherwise disabled)?
$domain_error = "An unknown error occured during registration, please try again later. Please contact the server admin if this problem persists.";
}
}
ElseIf (($_SERVER['REQUEST_METHOD']=='POST') AND ($_SESSION['phase'] == 2)) { //if form has been submitted and phase = 2
//store all posted values in sessions so we can use them again if needed
$_SESSION['url'] = $_POST['url'];
$_SESSION['email'] = $_POST['email'];
$_SESSION['category'] = $_POST['category'];
$_SESSION['title'] = $_POST['title'];
$_SESSION['description'] = $_POST['description'];
$_SESSION['keywords'] = $_POST['keywords'];
$_SESSION['favicon'] = $_POST['favicon'];
$_SESSION['language'] = $_POST['language'];
$_SESSION['revisit'] = $_POST['revisit'];
$_SESSION['robots'] = $_POST['robots'];
$send = 1; //form has been send
//send request to nl.ae server and receive answer in $domapi
$domapi = file_get_contents("http://nl.ae/domainapi/register.php?id=".$_SESSION['apiid']."&captcha=".$_POST['captcha']."&domain=".$_SESSION['domain']."&url=".$_SESSION['url']."&email=".$_SESSION['email']."&category=".$_SESSION['category']."&title=".$_SESSION['title']."&description=".$_SESSION['description']."&keywords=".$_SESSION['keywords']."&favicon=".$_SESSION['favicon']."&language=".$_SESSION['language']."&revisit=".$_SESSION['revisit']."&robots=".$_SESSION['robots']);
If ($domapi == 1) { //everything went alright, domain registered -> phase 3
$_SESSION['phase'] = 3;
}
ElseIf ($domapi == 0) { //ID was not given (you must have made a mistake in your script)
$domain_error = "Webmaster has forgotten to use the Anti-Bot CAPTCHA ID correctly, please contact the admin of this website.";
}
ElseIf ($domapi == -1) { //no CAPTCHA was given by user
$domain_error = "Please type over the code in the Anti-Bot CAPTCHA image to the inputfield.";
}
ElseIf ($domapi == -2) { //invalid CAPTCHA
$domain_error = "You haven't typed over the Anti-Bot CAPTCHA code correcly, please try again.";
}
ElseIf ($domapi == -3) { //invalid or empty domain given
$domain_error = "Please enter a valid domain.";
}
ElseIf ($domapi == -4) { //domain is unavailable for registration
$domain_error = "This domain is unavailable for registration, please choose an other domain.";
}
ElseIf ($domapi == -5) { //invalid URL
$domain_error = "Please enter a valid URL starting with http://, https://, www., callto://, callto:, mailto://, mailto: or irc://. It must have less then 2048 characters.";
}
ElseIf ($domapi == -6) { //invalid e-mail address
$domain_error = "Please fill in a valid e-mail address. You need it to activate your domain.";
}
ElseIf ($domapi == -7) { //invalid category
$domain_error = "Please choose a valid category for your domain.";
}
ElseIf ($domapi == -8) { //invalid title
$domain_error = "You have entered an invalid title. It must have more then 2 and less then 100 characters.";
}
ElseIf ($domapi == -9) { //invalid description
$domain_error = "You have entered an invalid description. It may not have more then 150 characters.";
}
ElseIf ($domapi == -10) { //invalid keywords
$domain_error = "You have entered invalid keywords. You may not enter more then 380 characters.";
}
ElseIf ($domapi == -11) { //invalid favicon
$domain_error = "You have entered an invalid favicon path. It must start with http:// or https://. It must end with .ico and may not contain more then 500 characters.";
}
ElseIf ($domapi == -12) { //invalid language
$domain_error = "You have entered an invalid language. It may not contain more then 50 characters.";
}
ElseIf ($domapi == -13) { //invalid revisit
$domain_error = "You have entered an invalid revisit value. It may not be less then 3 or more then 999. Enter a 0 or leave this field blank to let search engines decide (recommended).";
}
ElseIf ($domapi == -14) { //invalid robots
$domain_error = "You have entered an invalid robots value. It may not have more then 50 characters.";
}
Else { //this should not happen - maybe your server is running PHP on safe mode (or file_get_contents is otherwise disabled)?
$domain_error = "An unknown error has occured, please try again later.";
}
}
?>
<h2>nl.ae domain registration example script</h2>
<?php If ($_SESSION['phase'] == 1) { //if phase 1 show domain whois form ?>
<form method="post" action="<?php echo $_SERVER['PHP_SELF']; ?>">
<?php
If((isset($send)) AND ($send == 1)) {
If(isset($domain_error)) {
echo "<p style='color: red;'>".$domain_error."</p>";
}
}
?>
<p>www.<input type="text" maxlength="50" size="20" id="domain" name="domain" value="domain" />.nl.ae</p>
<input class="button" type="submit" value="check!" />
</form>
<?php } ElseIf ($_SESSION['phase'] == 2) { //if phase 2 show domain information input form
$_SESSION['apiid'] = file_get_contents("http://nl.ae/domainapi/reqid.php"); //identify with nl.ae server, used for CAPTCHA below ?>
<p>Congratulations, this domain is still available for registration. Please fill in the details below.</p>
<form method="post" action="<?php echo $_SERVER['PHP_SELF']; ?>">
<?php
If((isset($send)) AND ($send == 1)) {
If(isset($domain_error)) {
echo "<p style='color: red;'>".$domain_error."</p>";
}
}
?>
<p><b>Required Fields (these must be filled in)</b><br />
Domain: www.<?php echo $_SESSION['domain']; ?>.nl.ae<br />
Redirect URL: <input type="text" id="url" name="url" value="<?php if (isset($_SESSION['url'])) { echo $_SESSION['url']; } else { echo "http://"; } ?>" /><br />
E-mail address: <input type="text" id="email" name="email" value="<?php if (isset($_SESSION['email'])) { echo $_SESSION['email']; } else { echo "email@address.com"; } ?>" /><br />
Category: <select id="category" name="category">
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "none")) { echo 'selected="selected"'; } ?> value="none">Choose --></option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "blogs")) { echo 'selected="selected"'; } ?> value="blogs">Blogs</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "business")) { echo 'selected="selected"'; } ?> value="business">Business</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "computers")) { echo 'selected="selected"'; } ?> value="computers">Computers and Internet</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "education")) { echo 'selected="selected"'; } ?> value="education">Education</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "entertainement")) { echo 'selected="selected"'; } ?> value="entertainement">Entertainement</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "games")) { echo 'selected="selected"'; } ?> value="games">Games</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "health")) { echo 'selected="selected"'; } ?> value="health">Health</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "literature")) { echo 'selected="selected"'; } ?> value="literature">Literature and Culture</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "miscelaneous")) { echo 'selected="selected"'; } ?> value="miscelaneous">Miscelaneous</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "multimedia")) { echo 'selected="selected"'; } ?> value="multimedia">Multimedia</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "religion")) { echo 'selected="selected"'; } ?> value="religion">Religion</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "science")) { echo 'selected="selected"'; } ?> value="science">Science</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "society")) { echo 'selected="selected"'; } ?> value="society">Society</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "sport")) { echo 'selected="selected"'; } ?> value="sport">Sport</option>
<option <?php if ((isset($_SESSION['category'])) AND ($_SESSION['category'] == "teen")) { echo 'selected="selected"'; } ?> value="teen">Teen</option>
</select><br /></p>
<p><b>Optional Fields (these can be left empty)</b><br />
Domain title: <input type="text" id="title" name="title" value="<?php if (isset($_SESSION['title'])) { echo $_SESSION['title']; } else { echo "Welcome to my site!"; } ?>" /><br />
Description: <input type="text" id="description" name="description" value="<?php if (isset($_SESSION['description'])) { echo $_SESSION['description']; } ?>" /><br />
Keywords: <input type="text" id="keywords" name="keywords" value="<?php if (isset($_SESSION['keywords'])) { echo $_SESSION['keywords']; } ?>" /><br />
Favicon: <input type="text" id="favicon" name="favicon" value="<?php if (isset($_SESSION['favicon'])) { echo $_SESSION['favicon']; } else { echo "http://nl.ae/images/favicon.ico"; } ?>" /><br />
Language: <input type="text" id="language" name="language" value="<?php if (isset($_SESSION['language'])) { echo $_SESSION['language']; } ?>" /><br />
Revisit: <input type="text" id="revisit" name="revisit" value="<?php if (isset($_SESSION['revisit'])) { echo $_SESSION['revisit']; } else { echo 0; } ?>" /> days<br />
Robots: <input type="text" id="robots" name="robots" value="<?php if (isset($_SESSION['robots'])) { echo $_SESSION['robots']; } else { echo "index, follow"; } ?>" /></p>
<p><b>Anti-Bot Verification</b><br />
Please copy the code shown in the image to the inputfield below.<br />
<img src="http://nl.ae/domainapi/captcha.php?id=<?php echo $_SESSION['apiid']; // the ID received earlier this session (see above)?>" title="Please copy the code shown in the image to the inputfield below." /><br />
<input type="text" id="captcha" name="captcha" value="" />
</p>
<input class="button" type="submit" value="register domain!" />
</form>
<?php } ElseIf ($_SESSION['phase'] == 3) { //if phase 3 show confirmation page
$_SESSION['phase'] = 1; //reset phase to 1 so user can register a new domain on refresh ?>
<p>Congratulations! Your domain has been registered succesfully. Please login at <a href="http://www.login.nl.ae">www.login.nl.ae</a> using the account information send to your e-mail address to activate your domain. Your domain will be automatically removed if it is not activated within 7 days. We thus recommend you to activate it immediately.</p><p><a href="<?php echo $_SERVER['PHP_SELF']; ?>">Register another domain!</a></p>
<?php } ?>
Credit
Please credit us by placing an URL to our site on your homepage, for example:
Alternatively you can post a whois form leading to our free nl.ae domain check:
Or, you can show a simple image with a link:
Terms of Service
Please note that by using our API you agree to our Terms of Service. You must also link to our Terms of Service (www.tos.nl.ae) and inform your users that they must accept these before using our service.
Sponsors
Please take a look at our sponsors.
