Application Programming Interface

DNSapp.net features an Application Programming Interface (API) to allow you to connect programmatically to the service. This service is provided free-of-charge for subscribers and trial members.

Rubygem

If you are using Ruby you can use the gem we have released.

This eases the usage of the API.

Find more information here http://github.com/mmriis/dnsapp

Introduction

The API is RESTful. This means that all resources are accessed in a nested format, eg.


/domains
/domains/<id>
/domains/<id>/records
/domains/<id>/records/<id>

Basically you can GET/POST/PUT/DELETE on all resources.

Issueing a GET request on a collection (eg. domains) will result in a list, whereas a GET request on a specific object will result in details about that object (eg. GET /domains/1 where 1 is the ID of the domain).

Connecting

In order to connect to the API just must connect to the base URL. All resources are available under the base URL.

  https://dnsapp.net

Connecting via SSL (HTTPS) ensures that your password etc. is not transmitted in clear text.

Authentication

You must authenticate yourself to the API. This is accomplished via HTTP Basic Authentication. This means that you must specify your credentials at every operation. Most libraries feature an easy way to accomplish this. If not you can always manually add the following header:

  Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Here the string QWxhZGRpbjpvcGVuIHNlc2FtZQ== is a Base64 encoding of the string Aladdin:open sesame.

In this example Aladdin would be the username and open sesame the password. And the resulting string would be computed using something like this:

  base64_encode("Aladdin:open sesame")

For more information see http://en.wikipedia.org/wiki/Basic_access_authentication

Data format

The API supports data responses in the formats JSON and XML.

You have two different methods of specifying which format you would like your response in.

You can either specify the format in the Accept header of your request eg. for XML.

  Accept: application/xml

You can also add the appropriate ending to your request. This for XML would be:

  GET https://dnsapp.net/domains.xml

For JSON you would use the file extension .json instead.

Listing all domains

To get a list of all domains in json-format.

  GET https://dnsapp.net/domains.json

Which would give you eg. the following response.

  
  [
      {
          domain: {
              name: 'dnsapp.net',
              created_at: '2010-10-01T11:22:02Z',
              updated_at: '2010-10-01T11:22:02Z',
              id: 1,
              user_id: 1,
              state: 'done',
              locked: true,
              expiration: "2012-02-16T13:51:31Z",
              handle: 'CNET-42342',
              authoritative: true,
          }
      },
      {
          domain: {
              name: 'dnsapp.org',
              created_at: '2010-10-01T11:22:10Z',
              updated_at: '2010-10-01T11:22:10Z',
              id: 2,
              user_id: 1,
              state: 'done',
              locked: true,
              expiration: "2012-02-20T11:01:13Z",
              handle: 'CORG-122312',
              authoritative: true,
          }
      }
  ]    

Creating a domain

To add a new domain you would issue a POST to /domains.

Here is an example of adding a new domain called mydomain.com.

  POST https://dnsapp.net/domains.json

POST variables:

  domain[name]=mydomain.com

Response:

  HTTP/1.1 201 Created
  Location: https://dnsapp.net/domains/3
  Content-Type: application/json; charset=utf-8
  (extra headers removed)
  {
    domain: {
      name: 'mydomain.com',
      created_at: '2010-10-01T11:34:52Z',
      updated_at: '2010-10-01T11:34:52Z',
      id: 3,
      user_id: 1,
      auth_id: null,
      expiration: null,
      authoritative: false,
      status: 'unknown',
      locked: true,    
      handle: null
    }
  }

Here you can see that the server replies 201 Created. So everything is alright and the object has been created. Also the object is returned in the response. Here we can see that it has been given the id: 3 and user_id: 1.

Creating a domain with WHOIS data

Sometimes you might wish to fill in WHOIS data. This is needed when registering a domain through our API.

The POST call allows you to specify the following extra variables:

  domain[name]=example.org
  domain[whois_attributes][name]=Morten M Riis
  domain[whois_attributes][address_1]=Gammeltorv 8, 2.
  domain[whois_attributes][zip]=DK-1457
  domain[whois_attributes][city]=Copenhagen K
  domain[whois_attributes][email]=support@dnsapp.net
  domain[whois_attributes][country]=DK
  domain[whois_attributes][phone]=+4546951011
  
  # optional variables:
  domain[whois_attributes][organization]=DNSApp.net
  domain[whois_attributes][address_2]=
  domain[whois_attributes][state]=
  domain[whois_attributes][vat_id]=DK30505166
  domain[whois_attributes][fax]=

Note: It is important that the country variable is specified as a two letter country code (ISO 3166-1 alpha-2).
Note: Phone/fax number must begin with + eg. +45 for Denmark and can only contain numbers, dashes and spaces.

Showing a domain

To get the details of a domain you issue a GET to /domains/<id>.<format>.

Substitute <id> with the domains ID and format with either xml or json.

Example response:


HTTP/1.1 200 OK
Location: https://dnsapp.net/domains/3
Content-Type: application/json; charset=utf-8
(extra headers removed)
{
domain: {
name: ‘mydomain.com’,
created_at: ‘2010-10-01T11:34:52Z’,
updated_at: ‘2010-10-01T11:34:52Z’,
id: 3,
user_id: 1,
auth_id: null,
expiration: null,
authoritative: false,
status: ‘unknown’,
locked: true
}
}

Updating a domain

Updating / editing a domain isn’t possible since name change etc. doesn’t make sense for domains.

Deleting a domain

To delete a domain you issue a DELETE to /domains/<id>.<format>

As before substitute <id> with the domains ID and format with either xml or json.

Please note that domains that are in the process of being registered or transferred cannot be deleted.

Listing all records

To get a list of all records in json-format for domain with ID <id>.

  GET https://dnsapp.net/domains/<id>/records.json

Which would give you e.g. the following response.

  HTTP/1.1 200 OK
  (extra headers removed)
  
  [
      {
          record: {
              name: '%d',
              created_at: '2010-11-02T20:46:52Z',
              ttl: 3600,
              updated_at: '2010-12-09T21:04:39Z',
              domain_id: 3,
              id: 30,
              type: 'SOA',
              content: 'ns1.dnsapp.net webmaster.mydomain.com 1291928679',
              prio: null
          }
      },
      {
          record: {
              name: '%d',
              created_at: '2010-11-02T20:46:52Z',
              ttl: 43200,
              updated_at: '2010-11-02T20:46:52Z',
              domain_id: 3,
              id: 31,
              type: 'NS',
              content: 'ns1.dnsapp.net',
              prio: null
          }
      },
    ...
    ]    

Creating a record

Just as with domains you create a record by issuing a POST to /domains/<id>/records.<format>.

Substitute <id> with the domains ID and format with either xml or json.

Example:

  POST https://dnsapp.net/domains/3/records.json

POST variables:

  record[name]=%d
  record[content]=1.2.3.4
  record[type]=A
  record[ttl]=3600

Response:

  HTTP/1.1 201 Created
  Location: https://dnsapp.net/domains/3/records/14
  Content-Type: application/json; charset=utf-8
  (extra headers removed)
  {
      record: {
          name: '%d',
          created_at: '2010-12-09T21:04:39Z',
          ttl: 3600,
          updated_at: '2010-12-09T21:04:39Z',
          domain_id: 3,
          id: 14,
          type: 'A',
          content: '1.2.3.4',
          prio: null
      }
  }

So now we have added an A record for our domain that point to the IP 1.2.3.4.

Showing a record

As with domains the method is a GET to /domains/<domain-id>/records/<record-id>.

Please see showing a domain for reference.

Updating a record

This API call is also similar to updating a domain. Issue a PUT to /domains/<domain-id>/records/<record-id>.

The POST variables are the same as for creating a record.

Deleting a record

This is similar to deleting a domain. Issue a DELETE to /domains/<domain-id>/records/<record-id>.<format>.

Substitute <domain-id> with the domains ID, <record-id> with the records ID and format with either xml or json.

Checking to see if a domain is available

You can check if a given domain is available for registration. The response will be a plain text true or false.

Note: This only works for domain TLDs that can be registered through us.

Example:

  GET https://dnsapp.net/domains/available/example.org

Response:

  HTTP/1.1 200 OK
  Content-Type: text/plain
  (extra headers removed)

  false

Domain price

You can check the current domain price like so, where <id> is the domain ID.

  GET https://dnsapp.net/domains/<id>/price

Response:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  (extra headers removed)

  {"price":12.99,"vat_amount":3.25}

So here the price would be $12.99 and the VAT amount (if applicable) $3.25.

Buying a domain

You can buy domains via our API. But it requires you to have a credit with your account. You must pay for a certain credit amount in advance.

If you wish to use this feature please contact us at support@dnsapp.net.

To buy domains, please follow this procedure:

1. Check if the domain is available (see section entitled Checking to see if a domain is available).

2. Create the domain as you would normally do (see section entitled Creating a domain with WHOIS data).
Note: You must supply the domain creation with whois data. This is very important.

3. Check the price of the domain (see section entitled Domain price).

4. Optional: Check if you have the available credit (see section entitled Checking your credit).

5. Make a POST call like so:

POST https://dnsapp.net/domains/<id>/buy
Response:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
(extra headers removed)
{"message":"ok"}

6. Follow up on the domain status by checking the state attribute (see section entitled Showing a domain).

Checking your credit

You can check your available credit like so:

  GET https://dnsapp.net/users/credit

Response:

  HTTP/1.1 200 OK
  Content-Type: application/json; charset=utf-8
  (extra headers removed)

  {"credit":62.52}

So here we have a credit of $62.52.

Privacy Protection

You can enable or disable Privacy Protection like this:

  POST https://dnsapp.net/domains/<id>/enable_privacy_protection
  POST https://dnsapp.net/domains/<id>/disable_privacy_protection

Response code 202 means that the request was accepted and will be processed. Code 400 means error – please refer to the message returned in the response.