Skip to content

Commit

Permalink
* Add some formating to the README to differentiate between sections
Browse files Browse the repository at this point in the history
* Add example code for how to create a zone configuration
  • Loading branch information
pingwin committed May 16, 2013
1 parent 8631f49 commit b914e4a
Show file tree
Hide file tree
Showing 3 changed files with 170 additions and 36 deletions.
129 changes: 129 additions & 0 deletions README
@@ -1,4 +1,5 @@
DNS.com API Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This document serves as an overview to the DNS.com DNS service API.
To attain access to use the API approval must be applied for and granted
Expand All @@ -12,6 +13,7 @@ execute on these concepts to manage their account.


Technology Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To access the API special permission must be granted by the
administrators. Please contact DNS.com for this access, as well as
Expand All @@ -25,6 +27,7 @@ and will return a crafted JSON () formated data response.


For Testing and Integration Developers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The address to the sandbox location is . To interact with the sandbox
you must create your own account on it. The sandbox is an entire test
Expand All @@ -35,6 +38,7 @@ URL forward services are available for testing on port 8080.


A Note For Enterprise Users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Please be aware there is a variable replacement allowed. When records
are compiled the token %s is replaced with the domain name root zone.
Expand All @@ -53,6 +57,7 @@ example2.com CNAME → www.example2.com


Round Robin Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To implement round robin hosting for your domain all that is required is
to create 2 RR records. The multiple RR's will cycle during serving thus
Expand All @@ -62,6 +67,7 @@ giving the effect of round robin.


URL Forward Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To ensure we are always able to return a record for any host name
requested we require that if you want to use URL forwarding that a
Expand All @@ -72,6 +78,7 @@ be allowed to co-exist for a host name with other resource record types.


Terminology
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Operational Mode

Expand Down Expand Up @@ -111,10 +118,14 @@ the answer.


Required Fields
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AUTH_TOKEN - 28 Byte authorization token generated.



Example Request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

<?php
$AUTH_TOKEN = 'xxxxxxxxxxxxxxxxxxxxx';
Expand All @@ -131,6 +142,7 @@ echo $results;


Example Successful Response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{"meta": {
"success": 1
Expand All @@ -153,6 +165,7 @@ Example Successful Response


Example Error Response
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{"meta": {
"success": 0,
Expand All @@ -164,3 +177,119 @@ Example Error Response

Additionally: If a search or lookup fails will return in a HTTP header
response code 404. For Errors 500 and so on.




Example Code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

How to create a complete zone configuration.

This example will create this zone data with the DNS.com API.

$ORIGIN=example.com.

@ IN SOA ns1.dns.com. admin.example.com. (
2013051614,
3600,
1200,
1209600,
1800)

@ 1800 IN A 127.0.0.1
3600 IN MX 10 mail.example.com.
3600 IN TXT "v=spf1 ip4:127.0.0.2 +all"


www 1800 IN A 127.0.0.1

_xmpp-server._tcp 3600 IN SRV 0 5 5269 chat.example.com.

mail.example.com 3600 IN A 127.0.0.2
chat.example.com 3600 IN A 127.0.0.3

[Python]
from dnsdotcom_api import Provision

DOMAIN='example.com'

dnsObj = Provision(auth_token='XXXXXXXXXXXXXXXXXXXXXXXXX')

## creat the domain
domain = dnsObj.query('createDomain', {
'mode' : 'advanced',
'domain' : DOMAIN,
'rname' : 'admin.example.com',
})

assert domain['meta']['success']

domain_id = domain['meta']['id']

## when the domain is created the root hostname is created automaticly

r= dnsObj.query('createRRData', {
'domain' : DOMAIN,
'host' : '',
'type' : 'A',
'rdata' : '127.0.0.1',
'ttl' : 1800
})

dnsObj.query('createRRData', {
'domain' : DOMAIN,
'host' : '',
'type' : 'MX',
'priority' : 10,
'rdata' : 'mail.example.com.'
})

dnsObj.query('createRRData', {
'domain' : DOMAIN,
'host' : '',
'type' : 'TXT',
'rdata' : 'v=spf1 ip4:127.0.0.2 +all'
})

## Create the www host and rr
dnsObj.query('createHostname', {
'domain' : DOMAIN,
'host' : 'www'
})
## `default` cannot be used because the A record has a non-default TTL
dnsObj.query('createRRData', {
'domain' : DOMAIN,
'host' : 'www',
'type' : 'A',
'rdata' : '127.0.0.1',
'ttl' : 1800
})

## creating the jabber server SRV record
dnsObj.query('createHostname', {
'domain' : DOMAIN,
'host' : '_xmpp-server._tcp'
})
dnsObj.query('createRRData', {
'domain' : DOMAIN,
'host' : '_xmpp-server._tcp',
'type' : 'SRV',
'priority' : 0,
'weight' : 5,
'port' : 5269,
'rdata' : 'chat.example.com.'
})

## these hosts just direct to a single IP with a 1h TTL
dnsObj.query('createHostname', {
'domain' : DOMAIN,
'host' : 'mail',
'default' : '127.0.0.2'
})

dnsObj.query('createHostname', {
'domain' : DOMAIN,
'host' : 'chat',
'default' : '127.0.0.3'
})
1 change: 1 addition & 0 deletions sdk/python/__init__.py
@@ -0,0 +1 @@

76 changes: 40 additions & 36 deletions sdk/python/dnsdotcom_api.py
@@ -1,41 +1,45 @@
import httplib, urllib, json

class Provision(object):
def __init__(self, auth_token, sandbox=False):
self.auth_token = str(auth_token).upper()
self.sandbox = sandbox

def query(self, command, args={}):
if self.sandbox:
conn = httplib.HTTPConnection('sandbox.dns.com')
else:
conn = httplib.HTTPSConnection('app.dns.com')

# attach user authentication information if not already attached
if 'AUTH_TOKEN' not in args:
args['AUTH_TOKEN' ] = self.auth_token

# create query string
query_string = '/api/%s/?%s' % (command, urllib.urlencode(args))
conn.request('GET', query_string)

# read response
resp = conn.getresponse()
json_string = resp.read()
# print json_string
return json.loads(json_string)

def __init__(self, auth_token, sandbox=False, server=None):
self.auth_token = str(auth_token).upper()
self.sandbox = sandbox
self.server = server


def query(self, command, args={}):
if self.server:
conn = httplib.HTTPConnection(self.server)
else:
if self.sandbox:
conn = httplib.HTTPConnection('sandbox.dns.com')
else:
conn = httplib.HTTPSConnection('app.dns.com')

# attach user authentication information if not already attached
if 'AUTH_TOKEN' not in args:
args['AUTH_TOKEN' ] = self.auth_token

# create query string
query_string = '/api/%s/?%s' % (command, urllib.urlencode(args))
conn.request('GET', query_string)

# read response
resp = conn.getresponse()
json_string = resp.read()
# print json_string
return json.loads(json_string)


if __name__ == "__main__":
dnsObj = Provision(
auth_token = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXX',
sandbox = False
)
result = dnsObj.query('getDomains')

if not result['meta']['success']:
raise Exception('Error: %s' % result['meta']['error'])

import pprint
print pprint.pprint(result)

dnsObj = Provision(
auth_token = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXX',
sandbox = False
)
result = dnsObj.query('getDomains')

if not result['meta']['success']:
raise Exception('Error: %s' % result['meta']['error'])

import pprint
print pprint.pprint(result)

0 comments on commit b914e4a

Please sign in to comment.