:doctype: book
:toc: = DnsMadeEasy -- Ruby Client API Library
== Supporting Rest API SDK V2.0
NOTE: image:https://badge.fury.io/rb/dnsmadeeasy@2x.png["Gem Version", link="https://badge.fury.io/rb/dnsmadeeasy"]
image:https://img.shields.io/gem/dt/dnsmadeeasy?style=for-the-badge[Downloads,link="https://rubygems.org/gems/dnsmadeeasy"] image:https://img.shields.io/github/issues/kigster/dnsmadeeasy?style=for-the-badge&logo=appveyor[Github Issues,link="https://github.com/kigster/dnsmadeeasy/issues"] image:https://img.shields.io/github/forks/kigster/dnsmadeeasy?style=for-the-badge&logo=appveyor[Forks,link="https://github.com/kigster/dnsmadeeasy/network/members"] image:https://img.shields.io/github/stars/kigster/dnsmadeeasy?style=for-the-badge&logo=appveyor[Stars,link="https://github.com/kigster/dnsmadeeasy/stargazers"] image:https://img.shields.io/github/license/kigster/dnsmadeeasy?style=for-the-badge&logo=appveyor[License,link="https://github.com/kigster/dnsmadeeasy/blob/master/LICENSE.txt"]
image:https://github.com/kigster/dnsmadeeasy/workflows/Ruby/badge.svg?branch=master[Github Build,link=https://github.com/kigster/dnsmadeeasy/actions?query=workflow%3ARuby] image:https://travis-ci.org/kigster/dnsmadeeasy.svg?branch=master[Build Status,link=https://travis-ci.org/kigster/dnsmadeeasy]
image:https://api.codeclimate.com/v1/badges/7a48648b482b5a5c9257/maintainability[Maintainability,link=https://codeclimate.com/github/kigster/dnsmadeeasy/maintainability] image:https://api.codeclimate.com/v1/badges/7a48648b482b5a5c9257/test_coverage[Test Coverage,link=https://codeclimate.com/github/kigster/dnsmadeeasy/test_coverage]
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:
Client class, by passing your API key and API secrets as arguments: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
. 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.
....
~/.dnsmadeeasy/credentials.yml.Simple Credentials Format
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.
You can use the following method to access both simple and multi-account YAML configurations:
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:
@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:
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:
IRB > require 'dme' #=> true
IRB > require 'dnsmadeeasy/dme' #=> true IRB > DME.domains.data.map(&:name) ⤷ ["demo.gamespot.systems", "dev.gamespot.systems", "gamespot.live", "gamespot.systems", "prod.gamespot.systems" ]
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."]>
Next, let's fetch a particular domain, get it's records and compute the counts for each record type, such as 'A', 'NS', etc.
=== 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:
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_domaincreate_domainsdelete_domaindomaindomainsget_id_by_domain[discrete] ==== Records
records_forallbase_uricreate_a_recordcreate_aaaa_recordcreate_cname_recordcreate_httpred_recordcreate_mx_recordcreate_ns_recordcreate_ptr_recordcreate_recordcreate_spf_recordcreate_srv_recordcreate_txt_recorddelete_all_recordsdelete_recorddelete_recordsfind_allfind_firstfind_record_ids[discrete] ==== Secondary Domains
secondary_domainsecondary_domainsget_id_by_secondary_domaincreate_secondary_domaincreate_secondary_domainsupdate_secondary_domainsdelete_secondary_domain[discrete] ==== Secondary IpSets
secondary_ip_setsecondary_ip_setscreate_secondary_ip_setupdate_secondary_ip_setdelete_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:
gem install sym
sym -g -o 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:
api_key="12345678-a8f8-4466-ffff-2324aaaa9098" api_secret="43009899-abcc-ffcc-eeee-09f809808098" sym -ck my.key -e -s "${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 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:
❯ 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
For example:
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:
=== Managing Domains
NOTE: below we can be using @client instantiated with given key and secret, or
DME or DnsMadeEasy module.
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:
DME.create_domain('test.io')
To delete a domain:
=== Managing Secondary Domains
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:
DME.create_secondary_domain('test.io', IP_SET_ID)
To update a secondary domain:
To delete a secondary domain:
=== Managing Secondary IpSets
To retrieve all secondary IpSets:
To retrieve single ipSet:
To create an ipSet:
To update an ipSet:
To delete an ipSet:
=== Managing Records
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':
DME.find_record_ids ('test.io', 'woah', 'A')
find_record_id:DME.delete_record ('test.io', 123)
DME.delete_records ('test.io', [123, 143])
To create records of various types:
DME.create_record ('test.io', 'woah', 'A', '127.0.0.1', { 'ttl' => '60' })
==== Specialized Record Types
Below are the method calls for MX, SRV, and HTTPRED types:
DME.create_mx_record ('test.io', 'woah', 5, '127.0.0.1', {})
DME.create_srv_record ('test.io', 'woah', 1, 5, 80, '127.0.0.1', {})
To update a record:
To update several records:
To get the number of API requests remaining after a call:
NOTE: Information is not available until an API call has been made
To get the API request total limit after a call:
NOTE: Information is not available until an API call has been made
== Installation
Add this line to your application's Gemfile:
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:
dnsmadeeasy-rest-api gem== 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
Unknown package
We found that dnsmadeeasy demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 6 open source maintainers collaborating on the project.
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.
Security News
Opengrep continues building momentum with the alpha release of its Playground tool, demonstrating the project's rapid evolution just two months after its initial launch.
Security News
FSF files an amicus brief against Neo4j, defending the AGPL and warning against adding restrictive terms that undermine free software rights.
Research
Security News
Malicious PyPI package ‘set-utils’ steals Ethereum private keys by exfiltrating them through blockchain transactions via the Polygon RPC.