Gandi API Library
This is a short library to facilitate working with the Gandi API for domain registrations. While there are other libraries for this purpose this offers a more satisfying syntax.
Installation
As usual, just pop a reference to the gem into your Gemfile
and run
bundle
. Alternatively, just install the gem and require it manually.
gem 'viaduct-gandi', :require => 'gandi'
Configuration
Before you can run commands, you'll need to configure the library.
Gandi.apikey = 'abc123abc123abc123abc'
Gandi.mode = 'test' # or 'live'
Pricing
You can obtain pricing for registrations very easily. This example is the most basic form of obtaining a price. In this instance, it returns the price for registering a .com domain.
price = Gandi::Price.find('example.com')
price.action #=> 'create'
price.description #=> '.com'
price.price #=> 5.5
price.min_duration #=> 1
price.max_duration #=> 10
price.currency #=> 'GBP'
price.grid #=> 'E'
price.duration_unit #=> 'y'
There are a number of options which can be passed to method.
:action
- which service you will be using (create, renew, restore, transfer, plus others - create is default):currency
- which currency to return a price in (GBP, EUR or USD - GBP is default):grid
- your pricing grid (A,B,C,D,E - E is default):duration
- the duration of the registration (a positive interger - 1 is default)
Contacts
At the root of all domain registrations is a contact. Each contact has a unique handle
which identifies the contact and is needed for all registrations.
Creating a new contact
contact = Gandi::Contact.new
contact.type = 0
contact.first_name = 'Adam'
contact.last_name = 'Cooke'
contact.address = 'Unit 9 Winchester Place'
contact.city = 'Poole'
contact.country = 'GB'
contact.email_address = '[email protected]'
contact.phone = '+44.1202901101'
contact.password = 'randompasswordhere'
contact.save #=> true
contact.handle #=> 'AC1234-GANDI'
If an error occurs here there are two possible exceptions which may be raised (as the
same applies to updates). If a validation error is caught locally you will find a
Gandi::ValidationError
is raised otherwise you'll receive Gandi::DataError
with some
mostly uninteligiable garbage from the Gandi API.
Finding a contact
contact = Gandi::Contact.find('AC1234')
contact.first_name #=> 'Adam'
Updating a contact
To update a contact you need to find it and then make changes to its attributes followed by a save operation.
contact = Gandi::Contact.find('AC1234')
contact.phone = '+44.123451234'
contact.save
Determine if a contact can be associated with a domain
If you wish to see whether a contact is suitable for registration with a given domain, you can call this method on any contact.
contact.can_associate?('yourdomain.com')
This will return true or an error string straight from the Gandi API.
Return associated domains
If you wish to return all domains associated with a contact, you can call the domains
method.
contact.domains #=> [Gandi::Domain, Gandi::Domains, ...]
Domains
Once you have some contacts, you can easily manage domains through through the library.
TLDs
You can get a full list of TLDs which can be registered using the Gandi API using the method shown below. This will return an array of hashes with TLD information.
Gandi::Domains.tlds
Checking domain availability
Gandi provides a asyncronous method for checking domain availability. This library provides methods for determining availability both asyncronously and syncronously.
The asyncronous method accepts a number of domains to check and will return a hash of domains with their availability status. Any status which is 'pending' has not been determined yet and another call should be made in the near future to check again.
Gandi::Domain.check_availability('domain1.com', 'domain2.io') #=> {'domain1.com' => 'pending', 'domain2.io' => 'pending'}
The syncronous method will keep calling the API until it gets a non-pending status for all requested domains. Pending will only be returned if the status cannot be determined within 20 requests to the Gandi API.
Gandi::Domain.check_availability!('domain1.com', 'domain2.io') #=> {'domain1.com' => 'unavailable', 'domain2.io' => 'available'}
In addition to these methods, there is also a shorthand syncronous method for checking a single domain's status.
Gandi::Domain.available?('blahblahblah.com') #=> true or false
Create/register a new domain
In order to register a domain you need to create a new domain registration object. Once created the domain will be set up automatically. You should monitor the operation's 'step' attribute to see how things are progressing. When this is 'DONE', the domain has been registered.
if Gandi::Domain.available?('somedomain.com')
# Create a domain registration request
operation = Gandi::Domain.create('blahblahblah.com', :owner => 'ABC123')
# Monitor the operation status
operation.step #=> 'BILL'
operation.reload
operation.step #=> 'RUN'
operation.reload
operation.step #=> 'DONE' or 'ERROR'
operation.last_error #=> 'An error message here if failed'
else
# Domain is not available for registration
end
Looking up domain information
Once a domain has been registered, you can look it up using the following method.
domain = Gandi::Domain.find('blahblahblah.com')
domain.name #=> "blahblahblah.com"
domain.owner #=> A Gandi::Contact instance for the owner\
domain.partial? #=> false
In addition to these methods, there are a number of other attributes which are available. Consult with the Gandi docs for full details.
Changing contacts
To change the contact associated with a domain you can use the method below. You must pass the Gandi handle for the new contact.
domain = Gandi::Domain.find('blahblahblah.com')
operation = domain.change_contacts('admin' => 'DEF123', 'bill' => 'DEF123', 'tech' => 'DEF123')
Note: you cannot change the owner with this method and you don't need to change all the contact types. You should monitor the operation object to determine the status.
Renewing a domain
If you wish to renew a domain, you can use the method below.
domain = Gandi::Domain.find('blahblahblah.com')
operation = domain.renew(2015, 2)
The first argument here is the current expiry year and the second argument is the duration for the renewal. You should monitor the operation object to determine the status.
Restoring a domain
If you wish to restore a domain, you can use the method below.
domain = Gandi::Domain.find('blahblahblah.com')
operation = domain.restore(2)
The first argument here is the duration you wish to renew the domain for. You should monitor the operation object to determine the status.