DnsMadeEasy — Ruby Client API Library

You can find your API Key and Secret on the Account Settings Page of their UI.

Once you have the key and the secret, you have several choices:

• You can directly instantiate a new instance of the Client class, by passing your API key and API secrets as arguments:

   require 'dnsmadeeasy'
   @client = DnsMadeEasy::Api::Client.new(api_key, api_secret)

  1. Or, you can use the DnsMadeEasy.configure method to configure the key/secret pair, and then use DnsMadeEasy namespace to call the methods:

     require 'dnsmadeeasy'
     
     DnsMadeEasy.configure do |config|
       config.api_key = 'XXXX'
       config.api_secret = 'YYYY'
     end
     
     DnsMadeEasy.domains.data.first.name #=> 'moo.gamespot.com'

  2. Configuring API keys as above is easy, and can be done using environment variables. Alternatively, it may be convenient to store credentials in a YAML file.

Simple Credentials Format

Multi-Account Credentials Format

Below you see two accounts, with production key and secret being encrypted. See further below about encrypting your key and secrets.

You can use the following method to access both simple and multi-account YAML configurations:

1. Finally, you can use DME.credentials_from_file method that, unlike the method above, uses hash arguments:

Method above simply returns the credentials instance, but does not "save" it as the default credentials like configure_from_file. Therefore, if you need to access multiple accounts at the same time, this method will help you maintain multiple credentials at the same time.

Once you configure the keys, you can also use the shortcut module to save you some typing:

This has the advantage of being much shorter, but might conflict with existing modules in your Ruby VM. In this case, just do not require dnsmadeeasy/dme and only require dnsmadeeasy, and you’ll be fine. Otherwise, using DME is identical to using DnsMadeEasy, assuming you required dnsmadeeasy/dme file.

Since DnsMadeEasy is a bit of a mouthful, we decided to offer (in addition to the standard DnsMadeEasy namespace) the abbreviated module DME that simply forwards all messages to the module DnsMadeEasy. If in your Ruby VM there is no conflicting top-level class DME, then you can require 'dnsmadeeasy/dme' to get all of the DnsMadeEasy client library functionality without having to type the full name once. You can even do require 'dme'.

Whenever you require dme you also import the DnsMadeEasy namespace. The opposite is not true.

So if you DO have a name clash with another top-level module DME, simply do require 'dnsmadeeasy' and none of the DME module namespace will be loaded.

In a nutshell you have three ways to access all methods provided by the DnsMadeEasy::Api::Client class:

1. Instantiate and use the client class directly,

2. Use the top-level module DnsMadeEasy with require 'dnsmadeeasy'

3. Use the shortened top-level module DME with require 'dnsmadeeasy/dme'

Whether or not you are accessing a single account or multiple, it is recommended that you save your credentials (the API key and the secret) encrypted in the above mentioned file ~/.dnsmadeeasy/credentials.yml (or any file of you preference).

The examples that follow assume credentials have already been configured, and so we explore the API.

Using the DME module (or DnsMadeEasy if you prefer) you can access all of your records through the available API method calls, for example:

Next, let’s fetch a particular domain, get it’s records and compute the counts for each record type, such as 'A', 'NS', etc.

All public methods of this library return a Hash-like object, that is actually an instance of the class Hashie::Mash. Hashie::Mash supports the very useful ability to reach deeply nested hash values via a chain of method calls instead of using a train of square brackets. You can always convert it to a regular hash either to_hash or to_h on an instance of a Hashie::Mash to get a pure hash representation.

Note

to_hash converts the entire object to a regular hash, including the deeply nested hashes, while to_h only converts the primary object, but not the nested hashes. Here is an example below — in the first instance where we call to_h we are still able to call .value on the nested object, because only the top-level Mash has been converted into a Hash. In the second example, this call fails, because this method does not exist, and the value must be accessed via the square brackets:

For more information on the actual JSON API, please refer to the following PDF document.

• create_domain

• create_domains

• delete_domain

• domain

• domains

• get_id_by_domain

• records_for

• all

• base_uri

• create_a_record

• create_aaaa_record

• create_cname_record

• create_httpred_record

• create_mx_record

• create_ns_record

• create_ptr_record

• create_record

• create_spf_record

• create_srv_record

• create_txt_record

• delete_all_records

• delete_record

• delete_records

• find_all

• find_first

• find_record_ids

• secondary_domain

• secondary_domains

• get_id_by_secondary_domain

• create_secondary_domain

• create_secondary_domains

• update_secondary_domains

• delete_secondary_domain

• secondary_ip_set

• secondary_ip_sets

• create_secondary_ip_set

• update_secondary_ip_set

• delete_secondary_ip_set

It was mentioned above that the credentials YAML file may contain encrypted values. This facility is provided by the encryption gem Sym.

In order to encrypt your values, you need to perform the following steps:

Once you have the key generated, first, make sure to never commit this to any repo!. You can use 1Password for it, or something like that.

Let’s encrypt our actual API key:

Now, you place the encrypted values in the YAML file, and you can save "my.key" as the value against encryption_key: at the same level as the api_key and api_secret in the YAML file. This value can either point to a file path, or be a keychain name, or even a name of an environment variable. For full details, please see sym documentation.

To retrieve all domains:

To retreive the id of a domain by the domain name:

To retrieve the full domain record by domain name:

To create a domain:

To delete a domain:

To retrieve all secondary domains:

To retrieve secondary domain by id:

To retrieve the id of a domain by the secondary domain name:

To create a secondary domain:

To update a secondary domain:

To delete a secondary domain:

To retrieve all secondary IpSets:

To retrieve single ipSet:

To create an ipSet:

To update an ipSet:

To delete an ipSet:

To retrieve all records for a given domain name:

To find the record id for a given domain, name, and type:

This finds all of the IDs matching 'woah.test.io' type 'A':

To create records of various types:

$ bundle

$ gem install dnsmadeeasy