Registering a domain from Elixir

This is the final post in our getting started with the DNSimple API in Elixir series. You can find the previous ones here:

• Getting started with the DNSimple API in Elixir
• Checking domain availability with the DNSimple API in Elixir

In this post we are going to show you how to buy a domain using the Elixir API client.

Requirements

To register a domain using the Elixir API client you will need:

• An Elixir project with the dnsimple library installed.
• A DNSimple API access token.
• Your DNSimple account's account_id.

If you have not yet read it, you should read the getting started blog post, which will guide you through the necessary steps to obtain all of the above and prepare you for this tutorial.

Please, make sure to use our Sandbox Environment for your tests. Otherwise you will be spending real money and buying real domains while learning how to use our API.

Registering a domain

To register a domain you will call the register endpoint that is part of DNSimple's Registrar API. In the Elixir API client you will call the Registrar.register_domain/5 function.

The first two parameters of the function are the usual ones in the DNSimple library: The client struct contains all the authentication and configuration information, and the account_id is your account ID. The third one is domain_name, which is the name of the domain that you want to register. There is one other argument that I want to bring to your attention: attributes.

The attributes parameter corresponds to any extended attributes required by the registry when registering a domain. Some country code TLDs, or ccTLDs—like .es, .us, .uk, etc… require extra information when purchasing a domain. For example, to buy a Spanish domain, such as dnsimple.es, you will have to provide some sort of identification number, like your passport. You can use our TLD API to find out what extended attributes are required by each ccTLD.

Looking at the endpoint input documentation we can see that we can provide up to 5 attributes. However only one of them is mandatory: the registrant_id. (Note that extended_attributes and premium_price are also flagged as such but they are mandatory only under specific circumstances).

The registrant contact

The registrant_id of the contact in your DNSimple account that is used to register the domain. The contact information will show up in the WHOIS details of the domain (unless you have the WHOIS privacy service enabled). A registrant is required by ICANN policy and it is not possible for you to buy a domain without providing the corresponding contact information.

You can use the Contacts.list_contacts/3 function to list the contacts in your account and their corresponding IDs (be sure to replace TOKEN with your access token, and ACCOUNT_ID with your account id when you run this):

iex(1)> client = %Dnsimple.Client{access_token: "TOKEN", base_url: "https://api.sandbox.dnsimple.com"}
iex(2)> {:ok, response} = Dnsimple.Contacts.list_contacts(client, "ACCOUNT_ID")
iex(3)> Enum.map(response.data, &({&1.id, &1.email, "#{&1.first_name} #{&1.last_name}"}))
[{283, "javier@dnsimple.com", "Javier Acero"}]

As you can see I only have 1 contact in my account and the ID is 283.

If you have no contacts in your account you can use the API to create one: check out the Contacts.create_contact/4 function. If you are feeling lazy you can also create it from the DNSimple website.

Making the call

With the registrant_id we have all we need to register the domain:

iex(4)> {:ok, response} = Dnsimple.Registrar.register_domain(client, "ACCOUNT_ID", "bought-with-elixir.com", %{registrant_id: "REGISTRANT_ID"})
iex(5)> response.data
%Dnsimple.DomainRegistration{auto_renew: false,
 created_at: "2017-02-14T08:44:41Z", domain_id: 32015, expires_on: nil,
 id: 23627, period: 1, premium_price: nil, registrant_id: 283, state: "new",
 updated_at: "2017-02-14T08:44:41Z", whois_privacy: false}

What you get back is a DomainRegistration struct. It takes some time for the domain registration to complete, so we create one and return it immediately. Once it finishes you will receive an invoice for the domain registration and a notification in your DNSimple account's email address. And, of course, you will also get a webhook notification!

If any error occurs while starting the registration it will be returned as part of the response:

iex(6)> {:error, error} = Dnsimple.Registrar.register_domain(client, "ACCOUNT_ID", "dnsimple.com", %{registrant_id: "REGISTRANT_ID"})
iex(7)> error.message
"HTTP 400: The domain dnsimple.com is already registered"

That's all you have to do to register a domain with DNSimple using Elixir. Once you know what contact to use, registering a domain gets as simple as a function call.

There are more complex scenarios when registering ccTLD domains that require you to provide extended attributes or if the domain is considered premium by the registry. If you have any issues with those cases just drop us a line, support@dnsimple.com and we will be happy to help.

Share on Twitter and Facebook

Javier Acero

Programmer. Minimalist. Apple fanboy. Currently having fun at DNSimple. I love coffee and my cat.