Announcing DNSimple Ruby Gem v3

In the last couple of years we have been working hard on redesigning our API. Last month we launched the beta of our API v2 along with an initial version of two new official clients: Go and Ruby.

Today we are happy to announce the DNSimple Ruby client version 3.0.0, compatible with the API v2. Even though the new version of the API is still in beta, the Ruby client is now stable and ready for production.

What's hot

One of the major changes in this version is the inclusion of OAuth authentication. You can use the gem to generate the URL to start the OAuth dance:

client = Dnsimple::Client.new
client.oauth.authorize_url(client_id = "a1b2c3d4e5", state: rand(1..10000))
# => https://dnsimple.com/oauth/authorize?client_id=a1b2c3d4e5&state=9835&response_type=code

You can also use the client to get the access token:

auth = client.oauth.exchange_authorization_for_token(params["code"], client_id, client_secret, state: state)

Once you have the token registering a domain using our API is this easy:

client = Dnsimple::Client.new(access_token: auth.token)
client.registrar.register_domain(account_id = 1010, "my-new-domain.com", registrant_id: 1234)

A major feature of the new API is pagination. The Ruby client supports pagination out of the box: all the queries are paginated, you can inspect the details of the result set and specify a particular page.

result = client.domains.list_domains(account_id = 1010, query: { per_page: 2, page: 4 })
result.data             # paginated list of domains
result.page             # the current page
result.per_page         # the number of records per page
result.total_entries    # the total number of records
result.total_pages      # the total number of pages

If instead you want to fetch all the things, you can use the all method and let the client trigger the requests for you:

result = client.domains.all_domains(account_id = 1010)
result.data             # complete list of domains

Upgrading from dnsimple 2.x

If you are using any of the previous versions of the gem, the update is quite simple, but the underlying changes are rather significant. Although the new client was completely rewritten from scratch, it exposes the same interface of the existing 2.x releases.

You are encouraged to upgrade today in order to start using the latest version of our API and getting access to all the new features.

Please note that authentication has changed in API v2. In the new API client you need to replace the use of the API token with the new Oauth2 access token.

This is an example of authentication in dnsimple 2.x:

require 'dnsimple'

client = Dnsimple::Client.new(username: 'YOUR_USERNAME', api_token: 'YOUR_TOKEN')

# Fetch your details
user = client.users.user
puts "My email is #{user.email}"

To authenticate with the API v2 and the newer dnsimple gem, first go to your account (or user) section and create a new Oauth2 token. Once created, use the token to authenticate:

require 'dnsimple'

client = Dnsimple::Client.new(access_token: "a1b2c3")

# Fetch your details
response = client.identity.whoami   # execute the call
puts response.data                  # extract the relevant data from the response

Please give our new API Ruby client a try. We would love to hear your thoughts about all these changes.

Share on Twitter and Facebook

Javier Acero

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