This is a fully featured REST API client for DnsMadeEasy provider. DME is an excellent provider, and is highly recommended for their ease of use, very solid API, and great customer support. They also offer free DNS failover with business accounts, which is highly recommended for the arrays of load balancers in front of your app.

== Usage

DnsMadeEasy allows you to fetch, create, update DNS records, as long as you know your API key and the secret.

=== Setting up Credentials

You can find your API Key and Secret on the https://cp.dnsmadeeasy.com/account/info[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:

[source,ruby]

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

. Or, you can use the `DnsMadeEasy.configure` method to configure the key/secret pair, and then use `DnsMadeEasy` namespace to call the methods: + [source,ruby]

require 'dnsmadeeasy'

DnsMadeEasy.configure do |config| config.api_key = 'XXXX' config.api_secret = 'YYYY' end

DnsMadeEasy.domains.data.first.name #=> 'moo.gamespot.com'

. 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.

....

If filename is not specified, there is default location where this file is searched, which is ~/.dnsmadeeasy/credentials.yml.
If filename is provided, it will be read, and must conform to the following format: ....

Simple Credentials Format

[source,yaml]

file: ~/.dnsmadeeasy/credentials.yml

credentials: api_key: 2062259f-f666b17-b1fa3b48-042ad4030 api_secret: 2265bc3-e31ead-95b286312e-c215b6a0

Multi-Account Credentials Format

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

[source,yaml]

accounts: - name: development default_account: true credentials: api_key: 12345678-a8f8-4466-ffff-2324aaaa9098 api_secret: 43009899-abcc-ffcc-eeee-09f809808098 - name: production credentials: api_key: "BAhTOh1TeW06OkRhdGE6OldyYXBwZXJT............" api_secret: "BAhTOh1TeW06OkRhdGE6OldyYXBwZ............" encryption_key: spec/fixtures/sym.key

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

[source,ruby]

 require 'dnsmadeeasy'
 DnsMadeEasy.configure_from_file(file, account = nil, encryption_key = nil)

 # for example:
 DnsMadeEasy.configure_from_file('config/dme.yaml', 'production')
 DnsMadeEasy.domains #=> [ ... ]

 # or with encrypted key passed as an argument to decrypt YAML values:
 DnsMadeEasy.configure_from_file(
     'config/dme.yaml',
     'production',
     ENV['PRODUCTION_KEY'])

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

[source,ruby]

 @creds = DnsMadeEasy.credentials_from_file(file: 'my-creds.yml',
                                         account: 'production',
                                  encryption_key: 'MY_KEY')
 @creds.api_key    # => ...
 @creds.api_secret # => ...

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:

[source,ruby]

require 'dnsmadeeasy/dme' DME.domains.data.first.name #=> 'moo.gamespot.com'

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.

=== Which Namespace to Use? What is DME versus DnsMadeEasy?

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 http://www.rubydoc.info/gems/dnsmadeeasy/DnsMadeEasy/Api/Client[`DnsMadeEasy::Api::Client`] class:

. Instantiate and use the client class directly, . Use the top-level module DnsMadeEasy with require 'dnsmadeeasy' . Use the shortened top-level module DME with require 'dnsmadeeasy/dme'

=== Examples

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).

WARNING: DO NOT check that file into your repo! If you use encryption, do not check in your key!

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:

[source, ruby]

IRB > require 'dme' #=> true

Or you can also do

IRB > require 'dnsmadeeasy/dme' #=> true IRB > DME.domains.data.map(&:name) ⤷ ["demo.gamespot.systems", "dev.gamespot.systems", "gamespot.live", "gamespot.systems", "prod.gamespot.systems" ]

These have been read from the file ~/.dnsmadeeasy/credentials.yml

IRB > DME.api_key ⤷ "2062259f-f666b17-b1fa3b48-042ad4030"

IRB > DME.api_secret ⤷ "2265bc3-e31ead-95b286312e-c215b6a0"

IRB > DME.domain('gamespot.live').delegateNameServers ⤷ #<Hashie::Array ["ns-125-c.gandi.net.", "ns-129-a.gandi.net.", "ns-94-b.gandi.net."]>

Let's inspect the Client — after all, all methods are simply delegated to it:

IRB > @client = DME.client ⤷ #<DnsMadeEasy::Api::Client:0x00007fb6b416a4c8 @api_key="2062259f-f666b17-b1fa3b48-042ad4030", @api_secret="2265bc3-e31ead-95b286312e-c215b6a0", @options={}, @requests_remaining=149, @request_limit=150, @base_uri="https://api.dnsmadeeasy.com/V2.0">

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

[source,ruby]

IRB > records = DME.records_for('gamespot.com') IRB > [ records.totalPages, records.totalRecords ] ⤷ [1, 33] IRB > records.data.select{|f| f.type == 'A' }.map(&:name) ⤷ ["www", "vpn-us-east1", "vpn-us-east2", "staging", "yourmom"] IRB > types = records.data.map(&:type) ⤷ [....] IRB > require 'awesome_print' IRB > ap Hash[types.group_by {|x| x}.map {|k,v| [k,v.count]}] { "MX" => 2, "TXT" => 1, "CNAME" => 3, "NS" => 22, "A" => 5 }

=== Return Value Types

All public methods of this library return a Hash-like object, that is actually an instance of the class https://github.com/intridea/hashie[`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:

[source,ruby]

IRB > recs.to_h['data'].last.value ⤷ "54.200.26.233" IRB > recs.to_hash['data'].last.value "NoMethodError: undefined method `value` for #Hash:0x00007fe36fab0f68" IRB > recs.to_hash['data'].last['value'] ⤷ "54.200.26.233"

For more information on the actual JSON API, please refer to the http://www.dnsmadeeasy.com/integration/pdf/API-Docv2.pdf[following PDF document].

== Available Actions

Here is the complete of all methods supported by the DnsMadeEasy::Api::Client:

==== Domains

create_domain
create_domains
delete_domain
domain
domains
get_id_by_domain

[discrete] ==== Records

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

[discrete] ==== Secondary Domains

secondary_domain
secondary_domains
get_id_by_secondary_domain
create_secondary_domain
create_secondary_domains
update_secondary_domains
delete_secondary_domain

[discrete] ==== Secondary IpSets

secondary_ip_set
secondary_ip_sets
create_secondary_ip_set
update_secondary_ip_set
delete_secondary_ip_set

++++++++++++

=== Encryption

It was mentioned above that the credentials YAML file may contain encrypted values. This facility is provided by the encryption gem https://github.com/kigster/sym[Sym].

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

[source,bash]

gem install sym

let's generate a new key and save it to a file:

sym -g -o my.key

if you are on Mac OS-X, you can import the key into the KeyChain.

this creates an entry in the keychain named 'my.key' that can be used later.

sym -g -x my.key

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:

[source,bash]

api_key="12345678-a8f8-4466-ffff-2324aaaa9098" api_secret="43009899-abcc-ffcc-eeee-09f809808098" sym -ck my.key -e -s "${api_key}"

=> prints the encrypted value

On a mac, you can copy it to clipboard:

sym -ck my.key -e -s "${api_secret}" | pbcopy

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 https://github.com/kigster/sym#using-sym-with-the-command-line[sym documentation].

== CLI Client

This library offers a simple CLI client dme that maps the command line arguments to method arguments for corresponding actions:

image:.dme-help.png[Usage,width="80%",border="2"]

You can run dme operations to see the supported list of operations:

[source,bash]

❯ dme op Actions: Checkout the README and RubyDoc for the arguments to each operation, which is basically a method on a DnsMadeEasy::Api::Client instance. http://www.rubydoc.info/gems/dnsmadeeasy/DnsMadeEasy/Api/Client

Valid Operations Are: all base_uri create_a_record create_aaaa_record create_cname_record create_domain create_domains create_httpred_record create_mx_record create_ns_record create_ptr_record create_record create_secondary_domain create_secondary_domains create_secondary_ip_set create_spf_record create_srv_record create_txt_record delete_all_records delete_domain delete_record delete_records delete_secondary_domain delete_secondary_ip_set domain domains find_all find_first find_record_ids get_id_by_domain get_id_by_secondary_domain records_for secondary_domain secondary_domains secondary_ip_set secondary_ip_sets update_record update_records update_secondary_domains update_secondary_ip_set

For example:

[source,bash]

❯ dme domains moo.com

is equivalent to DME.domains("moo.com"). You can use any operation listed above, and output the result in either YAML or JSON (in addition to the default "awesome_print"), for example:

[source,bash]

❯ dme --yaml find_all moo.com www CNAME

dynamicDns: false failed: false gtdLocation: DEFAULT hardLink: false ttl: 60 failover: false monitor: false sourceId: 5861234 source: 1 name: www value: ec2-54-202-251-7.us-west-2.compute.amazonaws.com id: 43509989 type: CNAME

=== Managing Domains

NOTE: below we can be using @client instantiated with given key and secret, or DME or DnsMadeEasy module.

To retrieve all domains:

[source,ruby]

require 'dnsmadeeasy/dme' DME.domains

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

[source,ruby]

DME.get_id_by_domain('test.io')

To retrieve the full domain record by domain name:

[source,ruby]

DME.domain('test.io')

To create a domain:

[source,ruby]

DME.create_domain('test.io')

Multiple domains can be created by:

DME.create_domains(%w[test.io moo.re])

To delete a domain:

[source,ruby]

DME.delete_domain ('test.io')

=== Managing Secondary Domains

To retrieve all secondary domains:

[source,ruby]

DME.secondary_domains

To retrieve secondary domain by id:

[source,ruby]

DME.secondary_domain(domain_id)

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

[source,ruby]

DME.get_id_by_secondary_domain('test.io')

To create a secondary domain:

[source,ruby]

IP_SET_ID is id of ip_set you want to associate domain with

DME.create_secondary_domain('test.io', IP_SET_ID)

Multiple domains can be created by:

DME.create_secondary_domains(%w[test.io moo.re], IP_SET_ID)

To update a secondary domain:

[source,ruby]

IP_SET_ID is id of ip_set you want to associate

DOMAIN_ID is id of domain

DME.update_secondary_domains([DOMAIN_ID], IP_SET_ID)

To delete a secondary domain:

[source,ruby]

DME.delete_secondary_domain('test.io')

=== Managing Secondary IpSets

To retrieve all secondary IpSets:

[source,ruby]

DME.secondary_ip_sets

To retrieve single ipSet:

[source,ruby]

DME.secondary_ip_set(IP_SET_ID)

To create an ipSet:

[source,ruby]

IP_LIST is list of ips to be associated with this ip_set, like %w[8.8.8.8, 1.1.1.1]

DME.create_secondary_ip_set('ip-set-name', IP_LIST)

To update an ipSet:

[source,ruby]

DME.update_secondary_ip_set(IP_SET_ID, 'ip-list-name', IP_LIST)

To delete an ipSet:

[source,ruby]

DME.delete_secondary_ip_set(IP_SET_ID)

=== Managing Records

To retrieve all records for a given domain name:

[source,ruby]

DME.all('test.io')

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

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

[source,ruby]

DME.find_record_ids ('test.io', 'woah', 'A')

=> [ 234234, 2342345 ]

[source,ruby]

To delete a record by domain name and record id (the record id can be retrieved from `find_record_id`:

DME.delete_record ('test.io', 123)

To delete multiple records:

DME.delete_records ('test.io', [123, 143])

To delete all records in the domain:

DME.delete_all_records ('test.io')

To create records of various types:

[source,ruby]

The generic method:

DME.create_record ('test.io', 'woah', 'A', '127.0.0.1', { 'ttl' => '60' })

Specialized methods:

DME.create_a_record ('test.io', 'woah', '127.0.0.1', {}) DME.create_aaaa_record ('test.io', 'woah', '127.0.0.1', {}) DME.create_ptr_record ('test.io', 'woah', '127.0.0.1', {}) DME.create_txt_record ('test.io', 'woah', '127.0.0.1', {}) DME.create_cname_record ('test.io', 'woah', '127.0.0.1', {}) DME.create_ns_record ('test.io', 'woah', '127.0.0.1', {}) DME.create_spf_record ('test.io', 'woah', '127.0.0.1', {})

==== Specialized Record Types

Below are the method calls for MX, SRV, and HTTPRED types:

[source,ruby]

Arguments are: domain_name, name, priority, value, options = {}

DME.create_mx_record ('test.io', 'woah', 5, '127.0.0.1', {})

Arguments are: domain_name, name, priority, weight, port, value, options = {}

DME.create_srv_record ('test.io', 'woah', 1, 5, 80, '127.0.0.1', {})

Arguments are: domain_name, name, value, redirectType,

DME.create_httpred_record('test.io', 'woah', '127.0.0.1', 'STANDARD - 302', # description, keywords, title, options = {} 'a description', 'keywords', 'a title', {})

To update a record:

[source,ruby]

DME.update_record('test.io', 123, 'woah', 'A', '127.0.1.1', { 'ttl' => '60' })

To update several records:

[source,ruby]

DME.update_records('test.io', [ { 'id' => 123, 'name' => 'buddy', 'type' => 'A', 'value'=> '127.0.0.1' } ], { 'ttl' => '60' })

To get the number of API requests remaining after a call:

[source,ruby]

DME.requests_remaining #=> 19898

NOTE: Information is not available until an API call has been made

To get the API request total limit after a call:

[source,ruby]

DME.request_limit #=> 2342

NOTE: Information is not available until an API call has been made

== Installation

Add this line to your application's Gemfile:

[source,ruby]

gem 'dnsmadeeasy'

And then execute:

$ bundle

Or install it yourself:

$ gem install dnsmadeeasy

== Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exe rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, up date the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to https://rubygems.org[rubygems.org].

== Acknowledgements

The current maintainer https://github.com/kigster[Konstantin Gredeskoul] wishes to thank:

Arnoud Vermeer for the original dnsmadeeasy-rest-api gem
Andre Arko, Paul Henry, James Hart formerly of link:wanelo.com[Wanelo] fame, for bringing the REST API gem up to the level.
Phil Cohen, who graciously transferred the ownership of the name of this gem on RubyGems.org to the current maintainer.

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/dnsmadeeasy.

== License

The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].

FAQs

What is dnsmadeeasy?

Is dnsmadeeasy well maintained?

Package last updated on 15 Apr 2020

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

dnsmadeeasy

[source,ruby]

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

. Or, you can use the DnsMadeEasy.configure method to configure the key/secret pair, and then use DnsMadeEasy namespace to call the methods: + [source,ruby]

DnsMadeEasy.domains.data.first.name #=> 'moo.gamespot.com'

[source,yaml]

file: ~/.dnsmadeeasy/credentials.yml

credentials: api_key: 2062259f-f666b17-b1fa3b48-042ad4030 api_secret: 2265bc3-e31ead-95b286312e-c215b6a0

[source,yaml]

[source,ruby]

[source,ruby]

[source,ruby]

require 'dnsmadeeasy/dme' DME.domains.data.first.name #=> 'moo.gamespot.com'

[source, ruby]

Or you can also do

These have been read from the file ~/.dnsmadeeasy/credentials.yml

Let's inspect the Client — after all, all methods are simply delegated to it:

IRB > @client = DME.client ⤷ #<DnsMadeEasy::Api::Client:0x00007fb6b416a4c8 @api_key="2062259f-f666b17-b1fa3b48-042ad4030", @api_secret="2265bc3-e31ead-95b286312e-c215b6a0", @options={}, @requests_remaining=149, @request_limit=150, @base_uri="https://api.dnsmadeeasy.com/V2.0">

[source,ruby]

[source,ruby]

IRB > recs.to_h['data'].last.value ⤷ "54.200.26.233" IRB > recs.to_hash['data'].last.value "NoMethodError: undefined method value for #Hash:0x00007fe36fab0f68" IRB > recs.to_hash['data'].last['value'] ⤷ "54.200.26.233"

[source,bash]

let's generate a new key and save it to a file:

if you are on Mac OS-X, you can import the key into the KeyChain.

this creates an entry in the keychain named 'my.key' that can be used later.

sym -g -x my.key

[source,bash]

=> prints the encrypted value

On a mac, you can copy it to clipboard:

sym -ck my.key -e -s "${api_secret}" | pbcopy

[source,bash]

[source,bash]

❯ dme domains moo.com

[source,bash]

❯ dme --yaml find_all moo.com www CNAME

[source,ruby]

require 'dnsmadeeasy/dme' DME.domains

[source,ruby]

DME.get_id_by_domain('test.io')

[source,ruby]

DME.domain('test.io')

[source,ruby]

Multiple domains can be created by:

DME.create_domains(%w[test.io moo.re])

[source,ruby]

DME.delete_domain ('test.io')

[source,ruby]

DME.secondary_domains

[source,ruby]

DME.secondary_domain(domain_id)

[source,ruby]

DME.get_id_by_secondary_domain('test.io')

[source,ruby]

IP_SET_ID is id of ip_set you want to associate domain with

Multiple domains can be created by:

DME.create_secondary_domains(%w[test.io moo.re], IP_SET_ID)

[source,ruby]

IP_SET_ID is id of ip_set you want to associate

DOMAIN_ID is id of domain

DME.update_secondary_domains([DOMAIN_ID], IP_SET_ID)

[source,ruby]

DME.delete_secondary_domain('test.io')

[source,ruby]

DME.secondary_ip_sets

[source,ruby]

DME.secondary_ip_set(IP_SET_ID)

[source,ruby]

IP_LIST is list of ips to be associated with this ip_set, like %w[8.8.8.8, 1.1.1.1]

DME.create_secondary_ip_set('ip-set-name', IP_LIST)

[source,ruby]

DME.update_secondary_ip_set(IP_SET_ID, 'ip-list-name', IP_LIST)

[source,ruby]

DME.delete_secondary_ip_set(IP_SET_ID)

[source,ruby]

DME.all('test.io')

[source,ruby]

=> [ 234234, 2342345 ]

[source,ruby]

To delete a record by domain name and record id (the record id can be retrieved from find_record_id:

To delete multiple records:

. Or, you can use the `DnsMadeEasy.configure` method to configure the key/secret pair, and then use `DnsMadeEasy` namespace to call the methods: + [source,ruby]

IRB > recs.to_h['data'].last.value ⤷ "54.200.26.233" IRB > recs.to_hash['data'].last.value "NoMethodError: undefined method `value` for #Hash:0x00007fe36fab0f68" IRB > recs.to_hash['data'].last['value'] ⤷ "54.200.26.233"

To delete a record by domain name and record id (the record id can be retrieved from `find_record_id`: