Upload
dinhanh
View
252
Download
0
Embed Size (px)
Citation preview
CONTENTS
1 Gandi API Overview 11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Connect to the API server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 OT&E system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.5 Stateless . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.6 Rate limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.7 Security Fixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Introduction 52.1 XML-RPC Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 XML-RPC Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3 Gandi namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.4 Methods Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.5 Method Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.6 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.7 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.8 Operation steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Gandi Domain API 93.1 Domain API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Domain API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243.3 Domain API FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.4 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.5 Domain Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4 Gandi Contact API 374.1 Contact API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374.2 Contact API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404.3 Contact API FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444.4 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
5 Gandi Hosting API 535.1 Hosting API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535.2 Hosting Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595.3 Hosting API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595.4 Hosting Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6 Gandi Operation API 816.1 Operation API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
i
7 Gandi Catalog API 837.1 Catalog API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837.2 Catalog API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
8 Indices and tables 89
Index 91
ii
CHAPTER
ONE
GANDI API OVERVIEW
1.1 Introduction
The Gandi API provides a set of remote requests to manage resources.Currently you can manage your domain, contact, and hosting resources with the API.
1.2 Connect to the API server
1.2.1 URI
The PRODUCTION API URI is: https://rpc.gandi.net/xmlrpc/
The OT&E API URI is: https://rpc.ote.gandi.net/xmlrpc/
1.2.2 XML-RPC
The Gandi API is available via XML-RPC.
In Python, use the xmlrpclib module from the standard library:
>>> import xmlrpclib>>> api = xmlrpclib.ServerProxy(’https://rpc.gandi.net/xmlrpc/’)>>>>>> # assign your API key to a variable:>>> apikey = ’my 24-character API key’>>>>>> # Now you can call API methods.>>> # You must authenticate yourself by passing the API key as the first method’s argument>>> domains = api.domain.list(apikey)
Note: In Python 3 xmlrpclib has been renamed xmlrpc.client
In PHP 5, with the XML_RPC2 package from pear:
<?php// Library installed from PEARrequire_once ’XML/RPC2/Client.php’;
1
Gandi API Client Manual Documentation, Release 2.0-beta
// The first step is to connect to the API$domain_api = XML_RPC2_Client::create(
’https://rpc.gandi.net/xmlrpc/’,array( ’prefix’ => ’domain.’ )
);
// assign your API key to a variable$apikey = ’my 24-character API key’;
// Now you can call API method// You must authenticate yourself by passing the API key as the first method’s argument$result = $domain_api->list($apikey);
// dump the resultprint_r($result);?>
Note: XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have toinstanciante a client by namespace
With NodeJS, use the xmlrpc package from npm:
> var xmlrpc = require(’xmlrpc’)> var api = xmlrpc.createSecureClient({... host: ’rpc.gandi.net’,... port: 443,... path: ’/xmlrpc/’... })>> //Assign your API key to a variable> var apikey = ’my 24-character API key’>> // Now you can call API methods.> // You must authenticate yourself by passing the API key as the first method’s argument> api.methodCall(’domain.list’, [apikey], function (error, value) {... console.dir(value)... })
use XML::RPC;
my $api = XML::RPC->new(’https://rpc.gandi.net/xmlrpc/’);
# assign your API key to a variable:my $apikey = ’my 24-character API key’;
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentmy $domains = $api->call( ’domain.list’, $apikey );
require ’xmlrpc/client’
server = XMLRPC::Client.new2(’https://rpc.gandi.net/xmlrpc/’)
# assign your API key to a variable:apikey = ’my 24-character API key’
# Now you can call API methods.
2 Chapter 1. Gandi API Overview
Gandi API Client Manual Documentation, Release 2.0-beta
# You must authenticate yourself by passing the API key as the first method’s argumentdomains = server.call("domain.list", apikey)
Note: Store the API key in a safe place.
1.3 OT&E system
The OT&E acronym stands for Operational Test and Evaluation. It’s a test server for developers.
All operations in OT&E will be executed in OT&E registry system. So If you create a domain, it will be really createdbut not in production, only in the test server of the registry.
Warning: In OT&E system Gandi will not send any emails of error or acknowlegement.
Warning: Not all tlds will work in OT&E system. We try to have maximum connectivity with OT&E registrysystem, but sometimes there is no running OT&E registry system for a given tld.
1.4 Authentication
The API authenticates your account with its API key. Each procedure call takes the API key as its first argument:
>>> api.version.info(apikey)
<?phpprint_r($api_version.info($apikey))?>
> api.methodCall(’version.info’, [apikey], function (error, value) {... console.dir(value)... })
my $info = $api->call( ’version.info’, $apikey );
info = server.call(’version.info’, apikey)
1.5 Stateless
The API does not maintain a session.
State is managed on the client side. The API only maintains the description of the objects.In practice, an API call does not depend on other calls. It requires only the arguments it is passed.
1.6 Rate limiting
You can send 30 queries in 2 seconds to the Gandi API server.
1.3. OT&E system 3
Gandi API Client Manual Documentation, Release 2.0-beta
1.7 Security Fixes
Security fixes are applied in priority order to the latest stable version of the API, and then to other versions.The delay to fix older versions may vary depending on the complexity of the fix.
In practice, this means you should use the latest version of the API in order to benefit from faster security fixes.
4 Chapter 1. Gandi API Overview
CHAPTER
TWO
INTRODUCTION
The Gandi API is available via XML-RPC.
Here is a brief of what the XML-RPC standard is and how it is used with Gandi
2.1 XML-RPC Overview
XML-RPC is a webservice standard using http.
It is a simple way to invoke methods over HTTP POST.
For details please refer to the XML-RPC specification
2.2 XML-RPC Types
type descriptionint a 32-bit signed integer ( Gandi API uses positive integer )string a stringstruct a data structure that associates key-value ( a dict in Python, an array in php, an object in Javascript )array a data structure that is iterable. Often represented as a list.nil represents the undefined state of a parameter.
2.3 Gandi namespaces
Gandi API packages methods via namespaces. All hosting methods are prefixed with “hosting.”. The Gandi APIReference documents each namespace.
Note: Namespace are definitely not xmlns.
2.4 Methods Conventions
Objects domain (and its subobjects), contact, vm, disk, and iface usually provide a CRUD interface throughthe methods:api.obj.create(), api.obj.info(), api.obj.update(), api.obj.delete().
5
Gandi API Client Manual Documentation, Release 2.0-beta
As well as helper methods:api.obj.list(), api.obj.count().
Please refer to the specific documentation below to see where methods may differ from convention.By default all objects associated with apikey are matched in namespace.obj.list() andnamespace.obj.count().The filter parameter defines a mapping of keys and values to match.
class namespace.obj
list(apikey[, filters=nil])count(apikey[, filters=nil])info(apikey, _id)
create(apikey, _spec)
update(apikey, _id, _spec)
delete(apikey, _id)
Note:
• _id is usually an integer that uniquely identifies an object
• _spec is usually a mapping (dict in Python or struct in serialized formats like XML-RPC or JSON)
Note: namespace.obj is a dummy name as an example. In practice it will be something like hosting.vm, ordomain...
When filters are available for a method, the types for both filter value and attribute value are the same.
2.5 Method Signatures
In the Gandi API Reference, Parameters methods have names.Names are for readability. In XML-RPC, parameters are listed in order.
[ When a signature contains parameters between square brackets, [ and ], it means | the method has multiple possiblesignatures. | Bracketed parameters are optional. Default values are given after the =.
2.6 Filters
A filter is a struct with specific keys.
Filters are optional, and are used on methods namespace.obj.list() and namespace.obj.count()
6 Chapter 2. Introduction
Gandi API Client Manual Documentation, Release 2.0-beta
In addition to the filters available for the specific method, paging filters are also available fornamespace.obj.list() methods.
name values description* * a filtering clauseitems_per_page positive integer number of item per pagepage positive integer the page index (counting from 0)sort_by string the attribute to sort by
2.7 Operation
The methods which perform a modification return an operation.
You should use the operation.info method to monitor the progress of your requested operation until the stepvalue is DONE to ensure that your operation is successfully finished.
name values descriptionid positive integer unique identifier of your operationtype string identify the called methodsource string handle of the operation’s creatordate_created datetime as string when the operation was createddate_updated datetime as string when the operation was last updateddate_start datetime as string when the operation is scheduled to startstep string current operation state (Operation steps)[object]_id positive integer the unique identifier of the object in modification
In practice, domain.create returns an operation type ‘domain_create’, and the [object]_id is a domain_id.
This is generalized for every namespace.
2.8 Operation steps
Here is the life cycle of an operation:
• BILL: if the operation requires billing, this step means it’s currently working on billing
• WAIT: the billing is done, the operation is waiting to be processed.
• RUN: Gandi backends are currently handling the operation.
• DONE: the operation is done, end of operation’s life, no more processing will be performed.
• ERROR: an error occurred while the operation was processing, no more processing will be performed.
• CANCEL: the user decided to cancel the operation, no more processing will be performed.
All operations are created in a BILL step, if they require billing. All hosting operations (as described in this docu-mentation) are created in a WAIT state, as they do not need to be billed.
2.7. Operation 7
CHAPTER
THREE
GANDI DOMAIN API
3.1 Domain API
3.1.1 Introduction
The Gandi Domain API provides a set of remote requests to manage your domains.
3.1.2 Connecting to the API server
The Gandi Domain API is provided through a set of XML-RPC calls:
In Python, use the xmlrpclib module from the standard library:
>>> import xmlrpclib>>> api = xmlrpclib.ServerProxy(’https://rpc.gandi.net/xmlrpc/’)>>>>>> # assign your API key to a variable:>>> apikey = ’my 24-character API key’>>>>>> # Now you can call API methods.>>> # You must authenticate yourself by passing the API key as the first method’s argument>>> domains = api.domain.list(apikey)
Note: In Python 3 xmlrpclib has been renamed xmlrpc.client
In PHP 5, with the XML_RPC2 package from pear:
<?php// Library installed from PEARrequire_once ’XML/RPC2/Client.php’;
// The first step is to connect to the API$domain_api = XML_RPC2_Client::create(
’https://rpc.gandi.net/xmlrpc/’,array( ’prefix’ => ’domain.’ )
);
// assign your API key to a variable$apikey = ’my 24-character API key’;
// Now you can call API method
9
Gandi API Client Manual Documentation, Release 2.0-beta
// You must authenticate yourself by passing the API key as the first method’s argument$result = $domain_api->list($apikey);
// dump the resultprint_r($result);?>
Note: XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have toinstanciante a client by namespace
With NodeJS, use the xmlrpc package from npm:
> var xmlrpc = require(’xmlrpc’)> var api = xmlrpc.createSecureClient({... host: ’rpc.gandi.net’,... port: 443,... path: ’/xmlrpc/’... })>> //Assign your API key to a variable> var apikey = ’my 24-character API key’>> // Now you can call API methods.> // You must authenticate yourself by passing the API key as the first method’s argument> api.methodCall(’domain.list’, [apikey], function (error, value) {... console.dir(value)... })
use XML::RPC;
my $api = XML::RPC->new(’https://rpc.gandi.net/xmlrpc/’);
# assign your API key to a variable:my $apikey = ’my 24-character API key’;
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentmy $domains = $api->call( ’domain.list’, $apikey );
require ’xmlrpc/client’
server = XMLRPC::Client.new2(’https://rpc.gandi.net/xmlrpc/’)
# assign your API key to a variable:apikey = ’my 24-character API key’
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentdomains = server.call("domain.list", apikey)
Note: Store the API key in a safe place.
Note: the Domain API does not use HTTP authentication scheme. It uses a custom authentication mechanism basedon the API key.
10 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
3.1.3 Domain Creation
Steps to create a domain
1. Choose a Domain name
2. Choose or create contacts
3. Create the domain
Choose a domain name
First, you’ll need to check the domain availability via the domain.available() method:
>>> import time>>> domain = ’mydomain.net’>>> result = api.domain.available(apikey, [domain])>>> result{’mydomain.net’: ’pending’}>>> while result[domain] == ’pending’:
time.sleep(0.2)result = api.domain.available(apikey, [domain])
>>> result{’mydomain.net’: ’unavailable’}
<?php$domain = "mydomain.net";$result = $domain_api->available($apikey, array($domain));print_r($result);/*Array(
[mydomain.net] => pending)
*/while ( $result[$domain] == ’pending’) {
usleep(300000);$result = $domain_api->available($apikey, array($domain));
}print_r($result);/*Array(
[mydomain.net] => unavailable)
*/?>
> var domain = ’mydomain.net’> var callback = function(error, value) {... if ( value[domain] == ’pending’ ) {... console.log(’result is not yet ready’)... setTimeout(function() {... api.methodCall(’domain.available’, [apikey, [domain]], callback)... }, 200)... }... else {... console.dir(value)
3.1. Domain API 11
Gandi API Client Manual Documentation, Release 2.0-beta
... }
... }> api.methodCall(’domain.available’, [apikey, [domain]], callback)
use Time::HiRes qw();
my $domain = ’mydomain.net’;my $result = $api->call( ’domain.available’, $apikey, [$domain] );
print Data::Dumper->Dump( [$result] );#$VAR1 = {# ’mydomain.net’ => ’pending’#};$api->call( ’domain.available’, $apikey, [$domain] );$result = $api->call( ’domain.available’, $apikey, [$domain] );while ($result->{$domain} eq ’pending’) {
Time::HiRes::sleep(0.2);$result = $api->call( ’domain.available’, $apikey, [$domain] );
}print Data::Dumper->Dump( [$result] );#$VAR1 = {# ’mydomain.net’ => ’unavailable’#};
domain = ’mydomain.net’print server.call("domain.available", apikey, [domain]){"mydomain.net"=>"pending"}server.call("domain.available", apikey, [domain])while result[domain] == ’pending’ do
sleep 0.2result = server.call("domain.available", apikey, [domain])
endprint result{"mydomain.net"=>"unavailable"}
Note: the available method is asynchronous. You have to call it again if the result is not ready.
Choose or create contacts
You’ll need to associate your domain to an owner and 3 specific contacts : the admin, billing and technical contacts.You can choose existing contacts or, if needed, you can create new contacts, using the contact.create() (seeContact API).
Before, creating your domain, you can also check domain/contacts association rules with thecontact.can_associate_domain() method (see How-to check domain/contact association). Use thecontact.update() to correct the missing or incorrect contact attributes.
>>> association_spec = {... ’domain’: ’mydomain.fr’,... ’owner’: True,... ’admin’: True}>>> api.contact.can_associate_domain(apikey, ’FLN123-GANDI’, association_spec)True>>> api.contact.can_associate_domain(apikey, ’FLN123-GANDI’, association_spec)[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,
12 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]
<?php$contact_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’contact.’));$association_spec = array(
’domain’ => ’mydomain.fr’,’owner’ => true,’admin’ => true );
print_r( $contact_api->can_associate_domain($apikey, ’GG2647-GANDI’, $association_spec) );// 1// ORprint_r( $contact_api->can_associate_domain($apikey, ’FLN123-GANDI’, $association_spec) )/*[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,
’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...
},... ]
*/?>
> var association_spec = {... domain: ’mydomain.fr’,... owner: true,... admin: true}> api.methodCall(’contact.can_associate_domain’,... [apikey, ’FLN123-GANDI’, association_spec],... function (error, value) {... console.dir(value)... })
my $association_spec = {’domain’ => ’mydomain.fr’,’owner’ => True,’admin’ => True
};my $result = $api->call( ’contact.can_associate_domain’, $apikey, ’FLN123-GANDI’, $association_spec );print $result;True$result = $api->call( ’contact.can_associate_domain’, $apikey, ’FLN123-GANDI’, $association_spec );print $result;[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]
association_spec = {’domain’ => ’mydomain.fr’,’owner’=> true,’admin’=> true
}print server.call("contact.can_associate_domain", apikey, ’FLN123-GANDI’, association_spec)Trueprint server.call("contact.can_associate_domain", apikey, ’FLN123-GANDI’, association_spec)[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,
3.1. Domain API 13
Gandi API Client Manual Documentation, Release 2.0-beta
’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]
Create the domain
To create your domain use domain.create()
>>> domain_spec = {... ’owner’: ’FLN123-GANDI’,... ’admin’: ’FLN123-GANDI’,... ’bill’: ’FLN123-GANDI’,... ’tech’: ’FLN123-GANDI’,... ’nameservers’: [’a.dns.gandi-ote.net’, ’b.dns.gandi-ote.net’, ’c.dns.gandi-ote.net’],... ’duration’: 1}>>> op = api.domain.create(apikey, ’mydomain.net’, domain_spec)
<?php$domain_spec = array(
’owner’ => ’FLN123-GANDI’,’admin’ => ’FLN123-GANDI’,’bill’ => ’FLN123-GANDI’,’tech’ =>’FLN123-GANDI’,’nameservers’ => array(’a.dns.gandi-ote.net’, ’b.dns.gandi-ote.net’, ’c.dns.gandi-ote.net’),’duration’ => 1);
$op = $domain_api->__call(’create’,array($apikey, ’mydomain.net’, $domain_spec)));?>
note:: $domain_api->__call(“create”,...) call the rpc method domain.create()
see bug #13963 : RPC method named create can’t be called by client.
> var domain_spec = {... owner: ’FLN123-GANDI’,... admin: ’FLN123-GANDI’,... bill: ’FLN123-GANDI’,... tech: ’FLN123-GANDI’,... nameservers: [’a.dns.gandi-ote.net’, ’b.dns.gandi-ote.net’, ’c.dns.gandi-ote.net’],... duration: 1... }> api.methodCall(’domain.create’, [apikey, ’mydomain.net’, domain_spec],... function (error, value) {... console.dir(value)... })
my $domain_spec = {owner => ’FLN123-GANDI’,admin => ’FLN123-GANDI’,bill => ’FLN123-GANDI’,tech => ’FLN123-GANDI’,nameservers => [’a.dns.gandi-ote.net’, ’b.dns.gandi-ote.net’, ’c.dns.gandi-ote.net’],duration => 1,
};my $op = $api->call( ’domain.create’, $apikey, ’mydomain.net’, $domain_spec);
14 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
domain_spec = {’owner’ => ’FLN123-GANDI’,’admin’ => ’FLN123-GANDI’,’bill’ => ’FLN123-GANDI’,’tech’ => ’FLN123-GANDI’,’nameservers’ => [’a.dns.gandi-ote.net’, ’b.dns.gandi-ote.net’, ’c.dns.gandi-ote.net’],’duration’ => 1}
op = server.call("domain.create", apikey, ’mydomain.net’, domain_spec)
domain.create() takes the domain name as the first argument, the domain specification as its second argument.The domain specification provides the owner, admin, tech and bill contacts, the nameservers and the duration (in years)of your domain. When you ask for a domain creation, the domain will not be immediately available. You can trackthe process state by calling operation.info().
>>> op = api.operation.info(apikey, op[’id’])>>> op[’step’]’BILL’>>> op = api.operation.info(apikey, op[’id’])>>> op[’step’]’DONE’
<?php$op = $operation_api->info($apikey, $op[’id’])echo $op[’step’]//’BILL’
// and later...$op = $operation_api->info($apikey, $op[’id’])echo $op[’step’]//’DONE’?>
note:: XML_RPC2 works with ‘prefix’ in order to represent object notation.
> client.methodCall( ’operation.info’, [apikey, op[’id’]],... function(err, value) {... console.log(value.step)... // output ’BILL’... // but later, will print ’DONE’... })
my $operation = $api->call( ’operation.info’, $apikey, $op->{’id’} );print $operation->{’step’};’BILL’$operation = $api->call( ’operation.info’, $apikey, $op->{’id’} );print $operation->{’step’};’DONE’
op = server.call("operation.info", apikey, op{’id’})print op[’step’]’BILL’op = server.call("operation.info", apikey, op{’id’})print op[’step’]’DONE’
3.1. Domain API 15
Gandi API Client Manual Documentation, Release 2.0-beta
3.1.4 Domain Management
Getting Information
To get information, you can use the list, count, and info methods on the domain namespace.
>>> api.domain.info(apikey, ’mydomain.net’){’authinfo’: ’xxx’,’contacts’: {’admin’: {’handle’: ’FLN123-GANDI’, ’id’: 12345},
’bill’: {’handle’: ’FLN123-GANDI’, ’id’: 12345},’tech’: {’handle’: ’FLN123-GANDI’, ’id’: 12345},’admin’: {’handle’: ’FLN123-GANDI’, ’id’: 12345},’owner’: {’handle’: ’FLN123-GANDI’, ’id’: 12345},’reseller’: {’handle’: ’FLN123-GANDI’, ’id’: 12345},},
’tld’: ’com’,’date_created’: <DateTime ’20110304T16:48:17’ at 8d1072c>,’date_updated’: <DateTime ’20110506T15:34:17’ at 8d1072c>,’date_end’: <DateTime ’20120304T16:48:17’ at 8d1072c>,’fqdn’: ’mydomain.net’,’id’: 123,’nameservers’: [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],’status’: [’TransferProhibited’],’tags’: [’a’, ’b’, ’c’],’zone’: ’Gandi Zone 1’}
<?phpprint_r($domain_api->info($apikey, ’mydomain.net’));/*Array(
[status] => Array(
[0] => clientTransferProhibited)
[zone] => Gandi Zone 1[contacts] => Array
([owner] => Array
([handle] => FLN123-GANDI[id] => 12345
)
[admin] => Array(
[handle] => FLN123-GANDI[id] => 12345
)
[bill] => Array(
[handle] => FLN123-GANDI[id] => 12345
)
[tech] => Array
16 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
([handle] => FLN123-GANDI[id] => 12345
)
[reseller] =>)
[date_updated] => stdClass Object(
[scalar] => 20110902T18:27:34[timestamp] => 1314980854[xmlrpc_type] => datetime
)
[date_end] => stdClass Object(
[scalar] => 20120902T16:27:33[timestamp] => 1346596053[xmlrpc_type] => datetime
)
[tags] => Array()
[fqdn] => mydomain.net[nameservers] => Array
([0] => a.dns.gandi.net[1] => b.dns.gandi.net[2] => c.dns.gandi.net
)
[authinfo] => xxx[tld] => com[date_created] => stdClass Object
([scalar] => 20110902T16:27:34[timestamp] => 1314973654[xmlrpc_type] => datetime
)
[id] => 123)
*/
note:: XML_RPC2 works with a ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have toinstanciante a client by namespace
> api.methodCall(’domain.info’, [apikey, ’mydomain.net’],... function (error, value) {... console.dir(value)... }){ status: [ ’clientTransferProhibited’ ],zone: ’Gandi Zone 1’,
3.1. Domain API 17
Gandi API Client Manual Documentation, Release 2.0-beta
contacts:{ owner: { handle: ’FLN123-GANDI’, id: 1002336 },admin: { handle: ’FLN123-GANDI’, id: 1002336 },bill: { handle: ’FLN123-GANDI’, id: 1002336 },tech: { handle: ’FLN123-GANDI’, id: 1002336 },reseller: ’’ },
date_updated: Fri, 02 Sep 2011 16:27:34 GMT,date_end: Sun, 02 Sep 2012 14:27:33 GMT,tags: [],fqdn: ’mydomain.net’,nameservers: [ ’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’ ],authinfo: ’A3SB9$9j8u’,tld: ’com’,date_created: Fri, 02 Sep 2011 14:27:34 GMT,id: 2049696 }
my $result = $api->call( ’domain.info’, $apikey, ’mydomain.net’ );print Data::Dumper->Dump( [$result] );#$VAR1 = { ’authinfo’ => ’xxx’,#’contacts’ => {’admin’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},# ’bill’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},# ’tech’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},# ’admin’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},# ’owner’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},# ’reseller’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},# },# ’tld’ => ’com’,# ’date_created’ => ’20110304T16:48:17’,# ’date_updated’ => ’20110506T15:34:17’,# ’date_end’ => ’20120304T16:48:17’,# ’fqdn’ => ’mydomain.net’,# ’id’ => 123,# ’nameservers’ => [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],# ’status’ => [’TransferProhibited’],# ’tags’ => [’a’, ’b’, ’c’],# ’zone’ => ’Gandi Zone 1’};
print server.call("domain.info", apikey, ’mydomain.net’){’authinfo’ => ’xxx’,’contacts’ => {’admin’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},
’bill’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},’tech’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},’admin’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},’owner’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},’reseller’ => {’handle’ => ’FLN123-GANDI’, ’id’ => 12345},},
’tld’ => ’com’,’date_created’ => #<XMLRPC::DateTime:0x00000001f58970 @year=2011, @month=3, @day=4, @hour=16, @min=48, @sec=17>,’date_updated’ => #<XMLRPC::DateTime:0x00000001f58970 @year=2011, @month=5, @day=6, @hour=15, @min=34, @sec=17>,’date_end’ => #<XMLRPC::DateTime:0x00000001f58970 @year=2012, @month=3, @day=4, @hour=16, @min=48, @sec=17>,’fqdn’ => ’mydomain.net’,’id’ => 123,’nameservers’ => [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],’status’ => [’TransferProhibited’],’tags’ => [’a’, ’b’, ’c’],’zone’ => ’Gandi Zone 1’}
To get further information, you can use the following domain namespaces :
18 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
• domain.host
• domain.webredir
• domain.mailbox
• domain.packmail
• domain.forward
For each namespace, the info, list, count methods are available. Getting domain host information:
>>> api.domain.host.list(apikey, ’mydomain.net’)>>> api.domain.host.count(apikey, ’mydomain.net’)>>> api.domain.host.info(apikey, ’www.mydomain.net’)
<?php$domain_host_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.host.’));$domain_host_api->list($apikey, ’mydomain.net’);$domain_host_api->count($apikey, ’mydomain.net’);$domain_host_api->info($apikey, ’mydomain.net’);?>
> api.methodCall(’domain.host.list’, [apikey, ’mydomain.net’], function (error, value) {... console.dir(value)... })> api.methodCall(’domain.host.count’, [apikey, ’mydomain.net’], function (error, value) {... console.dir(value)... })> api.methodCall(’domain.host.info’, [apikey, ’www.mydomain.net’], function (error, value) {... console.dir(value)... })
$api->call( ’domain.host.list’, $apikey, ’mydomain.net’ );$api->call( ’domain.host.count’, $apikey, ’mydomain.net’ );$api->call( ’domain.host.info’, $apikey, ’www.mydomain.net’ );
server.call("domain.host.list", apikey, ’mydomain.net’)server.call("domain.host.count", apikey, ’mydomain.net’)server.call("domain.host.info", apikey, ’www.mydomain.net’)
Update a domain
The following attributes can be set/updated:
• domain.contacts-set-usage
• domain.status-set-usage
• domain.nameservers-usage
For each attribute you can perform the following actions. Updating domain contacts:
>>> contacts_spec = {... ’admin’: ’FLN123-GANDI’,... ’tech’: ’FLN123-GANDI’,... ’bill’: ’FLN123-GANDI’}>>> api.domain.contacts.set(apikey, ’mydomain.net’, contacts_spec)
3.1. Domain API 19
Gandi API Client Manual Documentation, Release 2.0-beta
<?php$domain_contacts_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.contacts.’));contacts_spec = array(
’admin’ => ’FLN123-GANDI’,’tech’ => ’FLN123-GANDI’,’bill’=> ’FLN123-GANDI’
);$domain_contacts_api->set($apikey, ’mydomain.net’, $contacts_spec);?>
> contacts_spec = {... ’admin’: ’FLN123-GANDI’,... ’tech’: ’FLN123-GANDI’,... ’bill’: ’FLN123-GANDI’}> api.methodCall(’domain.contacts.set’, [apikey, ’mydomain.net’, contacts_spec],... function (error, value) {... console.dir(value)... })
my $contacts_spec = {admin => ’FLN123-GANDI’,tech => ’FLN123-GANDI’,bill => ’FLN123-GANDI’
};$api->call( ’domain.contacts.set’, $apikey, ’mydomain.net’, $contacts_spec);
contacts_spec = {’admin’ => ’FLN123-GANDI’,’tech’ => ’FLN123-GANDI’,’bill’ => ’FLN123-GANDI’}
server.call("domain.contacts.set", apikey, ’mydomain.net’, contacts_spec)
(Un)Setting the clientTransferProhibited registry status on your domain:
>>> api.domain.status.lock(apikey, ’mydomain.net’)>>> api.domain.status.unlock(apikey, ’mydomain.net’)
<?php$domain_status_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.status.’));$domain_status_api->lock($apikey, ’mydomain.net’);$domain_status_api->unlock($apikey, ’mydomain.net’);?>
> api.methodCall(’domain.status.lock’, [apikey, ’mydomain.net’],... function (error, value) {... console.dir(value)... })> api.methodCall(’domain.status.unlock’, [apikey, ’mydomain.net’],... function (error, value) {... console.dir(value)... })
$api->call( ’domain.status.lock’, $apikey, ’mydomain.net’ );$api->call( ’domain.status.unlock’, $apikey, ’mydomain.net’ );
server.call("domain.status.lock", apikey, ’mydomain.net’)server.call("domain.status.unlock", apikey, ’mydomain.net’)
Updating the domain nameservers:
20 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
>>> api.domain.nameservers.set(apikey, ’mydomain.net’, \[’a.dns.mydomain.net’, ’b.dns.mydomain.net’, ’c.dns.mydomain.net’])
<?php$domain_nameservers_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.nameservers.’));$domain_nameservers_api->set($apikey, ’mydomain.net’,
array( ’a.dns.mydomain.net’, ’b.dns.mydomain.net’, ’c.dns.mydomain.net’));?>
> api.methodCall(’domain.nameservers.set’, ’mydomain.net’,[’a.dns.mydomain.net’, ’b.dns.mydomain.net’, ’c.dns.mydomain.net’])
... function (error, value) {
... console.dir(value)
... })
$api->call( ’domain.nameservers.set’, $apikey,’mydomain.net’, [’a.dns.mydomain.net’, ’b.dns.mydomain.net’, ’c.dns.mydomain.net’] );
server.call("domain.nameservers.set", apikey, ’mydomain.net’,[’a.dns.mydomain.net’, ’b.dns.mydomain.net’, ’c.dns.mydomain.net’])
The following domain namespaces are available:
• domain.host
For each namespace, the create, delete, set/update methods are available. Managing domain host :
>>> api.domain.host.create(apikey, ’dns1.mydomain.net’, [’1.2.3.4’])>>> api.domain.host.delete(apikey, ’dns1.mydomain.net’)
$domain_host_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.host.’));<?php$domain_host_api->create($apikey, ’dns1.mydomain.net’, array(’1.2.3.4’));$domain_host_api->delete($apikey, ’dns1.mydomain.net’);?>
> api.methodCall(’domain.host.create’, [apikey, ’dns1.mydomain.net’,[’1.2.3.4’]],... function (error, value) {... console.dir(value)... })> api.methodCall(’domain.host.delete’, [apikey, ’dns1.mydomain.net’],... function (error, value) {... console.dir(value)... })
$api->call( ’domain.host.create’, $apikey, ’dns1.mydomain.net’, [’1.2.3.4’] );$api->call( ’domain.host.delete’, $apikey, ’dns1.mydomain.net’ );
server.call("domain.host.create", apikey, ’dns1.mydomain.net’, [’1.2.3.4’])server.call("domain.host.delete", apikey, ’dns1.mydomain.net’)
3.1. Domain API 21
Gandi API Client Manual Documentation, Release 2.0-beta
3.1.5 Domain Processing
Renew a domain
>>> renew_spec = {... ’duration’: 1,... ’current_year’: 2011}>>> api.domain.renew(apikey, ’mydomain.net’, renew_spec)
<?php$renew_spec = array(’duration’=> 1,’current_year’=> 2011);
$domain_api->renew($apikey, ’mydomain.net’, $renew_spec);?>
> renew_spec = {... ’duration’: 1,... ’current_year’: 2011}> api.methodCall(’domain.renew’, [apikey, ’mydomain.net’],... function (error, value) {... console.dir(value)... })
$renew_spec = {’duration’ => 1,’current_year’ => 2011
};$api->call( ’domain.renew’, $apikey, ’mydomain.net’, $renew_spec );
renew_spec = {’duration’ => 1,’current_year’ => 2011}
server.call("domain.renew", apikey, ’mydomain.net’, renew_spec)
Transfer a domain to Gandi
>>> transfer_spec = {... ’owner’: ’FLN123-GANDI’,... ’admin’: ’FLN123-GANDI’,... ’tech’: ’FLN123-GANDI’,... ’bill’: ’FLN123-GANDI’,... ’nameservers’: [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],... ’authinfo’: ’xxx’,... ’duration’: 1}>>> api.domain.transferin.proceed(apikey, ’mydomain.net’, transfer_spec)
<?php$domain_transferin_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.transferin.’));$transfer_spec = array(
’owner’ => ’FLN123-GANDI’,’admin’ => ’FLN123-GANDI’,’tech’ => ’FLN123-GANDI’,’bill’ => ’FLN123-GANDI’,’nameservers’ => array(’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’),’authinfo’ => ’xxx’,
22 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
’duration’ => 1)$domain_transferin_api->proceed($apikey, ’mydomain.net’, transfer_spec);?>
> var transfer_spec = {> owner: ’FLN123-GANDI’,> admin: ’FLN123-GANDI’,> tech: ’FLN123-GANDI’,> bill: ’FLN123-GANDI’,> nameservers: [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],> authinfo: ’xxx’,> duration: 1}> api.methodCall(’domain.transferin.proceed’, [apikey, ’mydomain.net’, transfer_spec],... function (error, value) {... console.dir(value)... })
$transfer_spec = {owner => ’FLN123-GANDI’,admin => ’FLN123-GANDI’,tech => ’FLN123-GANDI’,bill => ’FLN123-GANDI’,nameservers => [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],authinfo => ’xxx’,duration => 1
};$api->call( ’domain.transferin.proceed’, $apikey, ’mydomain.net’, $transfer_spec );
transfer_spec = {’owner’ => ’FLN123-GANDI’,’admin’ => ’FLN123-GANDI’,’tech’ => ’FLN123-GANDI’,’bill’ => ’FLN123-GANDI’,’nameservers’ => [’a.dns.gandi.net’, ’b.dns.gandi.net’, ’c.dns.gandi.net’],’authinfo’ => ’xxx’,’duration’ => 1}
server.call("domain.transferin.proceed", apikey, ’mydomain.net’, transfer_spec)
Note: Due to registry limitations, you can create a transfer operation in OTE, but the command will fail at the registry.
3.1.6 Tld
List all tld available in API
>>> api.domain.tld.list(apikey)
<?php$domain_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.tld.’));$domain_api->list($apikey);?>
> api.methodCall(’domain.tld.list’, [apikey],... function (error, value) {... console.dir(value)... })
3.1. Domain API 23
Gandi API Client Manual Documentation, Release 2.0-beta
$api->call( ’domain.tld.list’, $apikey );
server.call("domain.tld.list", apikey)
List all tld by region, available in API
>>> api.domain.tld.region(apikey)
<?php$domain_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’domain.tld.’));$domain_api->region($apikey);?>
> api.methodCall(’domain.tld.region’, [apikey],... function (error, value) {... console.dir(value)... })
$api->call( ’domain.tld.region’, $apikey );
server.call("domain.tld.region", apikey)
3.2 Domain API Reference
3.2.1 domain
Domain API interface.
domain.available(apikey, fqdns)Check the availability of some domain names.
Parameters
• apikey (string) – user identification key.
• fqdns (array) – A non empty list of FQDNs.
Returns struct – A mapping of domain name with a status.
domain.count(apikey[, filters=nil])Count domains visible by this account.
Parameters
• apikey (string) – user identification key.
• filters (struct) – Options to filter the result (see Filters).
Returns int – The number of domains found.
domain.create(apikey, fqdn, params)Create a domain with the given information.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The name of the domain to create.
24 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
• params (struct) – description of the domain.
Returns struct – the domain_create operation dict
domain.info(apikey, fqdn)get domain information.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The domain name.
Returns struct – Information about the domain.
domain.list(apikey[, opts=nil])List domains that match the filter.
Available filters are:
•id
•tld
•fqdn
•owner
•admin
•tech
•bill
•status
•date_created
•date_registry_end
•date_end.
Parameters
• apikey (string) – user identification key.
• opts (struct) – Options to filter the result (see Filters).
Returns list of struct – list of domains
domain.renew(apikey, fqdn, params)Renew a domain.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The Domain to renew.
• params (struct) – The needed parameters for a renew.
Returns struct – the domain_renew operation dict
3.2. Domain API Reference 25
Gandi API Client Manual Documentation, Release 2.0-beta
3.2.2 domain.contacts
Domain’s contacts API interface.
domain.contacts.set(apikey, fqdn, contacts)Change domain’s contact.
Parameters
• apikey (string) – the user identification.
• fqdn (string) – the domain name.
• contacts (struct) – the list of contacts to update.
Returns struct – A domain_contact_change operation
3.2.3 domain.status
Domain status API interface.
For more information about status see the RFC 3731
domain.status.lock(apikey, fqdn)Lock a domain, set the ‘clientTransferProhibited’ status flag.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The fqdn of the domain to lock.
Returns struct – a domain_status_update operation.
domain.status.unlock(apikey, fqdn)Unlock a domain, unset the ‘clientTransferProhibited’ status flag.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The fqdn of the domain to unlock.
Returns struct – A domain_status_update operation.
3.2.4 domain.host
domain.host.count(apikey, fqdn[, opts=nil])Count the glue records / hosts of a domain.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The fqdn to count.
• opts (struct) – optional parameter to filter result (see Filters).
Returns int – The number of glue records per hosts
domain.host.create(apikey, hostname, ips)Create a host.
Parameters
26 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
• apikey (string) – user identification key.
• hostname (string) – The name of the host to create.
• ips (array) – list of IPs to create.
Returns struct – The create operation
domain.host.delete(apikey, hostname)Delete a host.
Parameters
• apikey (string) – user identification key.
• hostname (string) – The hostname of the Host to delete.
Returns struct – The delete operation
domain.host.info(apikey, hostname)Display host information for a given domain.
Parameters
• apikey (string) – user identification key.
• hostname (string) – The host to update.
Returns struct – The host information
domain.host.list(apikey, fqdn[, opts=nil])List the glue records / hosts for a given domain.
Parameters
• apikey (string) – user identification key.
• fqdn (string) – The fqdn for list.
• opts (struct) – optional parameter to filter list result (see Filters).
Returns struct – The list of records per hosts
domain.host.update(apikey, hostname, ips)Update a host.
Parameters
• apikey (string) – user identification key.
• hostname (string) – The hostname to update.
• ips (array) – list of IPs to set.
Returns struct – The update operation
3.2. Domain API Reference 27
Gandi API Client Manual Documentation, Release 2.0-beta
3.2.5 domain.mailbox
3.2.6 domain.mailbox.alias
3.2.7 domain.mailbox.responder
3.2.8 domain.forward
3.2.9 domain.packmail
3.2.10 domain.tld
Top level domain API interface.
domain.tld.list(apikey)Get the list of all available TLD extensions.
Parameters apikey (string) – the user identification.
Returns list of struct – A list of TLDs
domain.tld.region(apikey)Get the list of all available TLD extensions folded by region.
Parameters apikey (string) – the user identification.
Returns list of struct – A list of TLDs
3.2.11 domain.transferin
Incoming transfers domain API interface.
domain.transferin.proceed(apikey, fqdn, params)Transfer a domain.
Parameters
• apikey (string) – The user identification.
• fqdn (string) – The domain name.
• params (struct) – domain to transfer in.
Returns struct – the domain_transfer_in operation dict
3.2.12 domain.nameservers
Public API to manage domain’s nameservers.
domain.nameservers.set(apikey, fqdn, nameservers)Define the nameservers for a given domain.
Parameters
• apikey (string) – The user identification.
• fqdn (string) – The fqdn of the domain to alter.
• nameservers (array) – list of nameservers.
28 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
Returns struct – The operation.
3.2.13 Mappings
Fully Qualified Domain Name
http://en.wikipedia.org/wiki/Fully_qualified_domain_name
Fully Qualified Domain Name List
A list of fqdn, parameter of domain.available():
Domain Available Result
A struct returned by domain.available():
Keys are the Fully Qualified Domain Name List
Values are:
• pending : Result is not yet ready, recall the method in order to get the result
• available : The domain name is available
• available_reserved : The domain is reserved under particular conditions
• available_preorder : The domain can be pre-ordered
• unavailable : The domain is not available
• unavailable_premium: The domain is not available
• unavailable_restricted: The domain is not available (forbidden)
• error_invalid: The provided fqdn is not a valid domain name
• error_refused : The service is temporarily down
• error_timeout : The service is temporarily down
• error_unknown : The service is temporarily down (internal server error)
Domain Creation Mapping
A struct, parameter of domain.create():
name type mandatory descriptionowner string mandatory the owner contact handle of the domainadmin string mandatory the administrative contact handle of the domaintech string mandatory the technical contact handle of the domainbill string mandatory the billing contact handle of the domainnameservers list of string mandatory the nameserver list of the domainduration positive integer mandatory the duration (in years) you wish the domain to be created forauthinfo string optional the authorization token – will be set randomly if not specifiedlang string optional for IDN domains, the ISO-639-2 code of the domain’s language
Note: only resellers can set a different owner than themselves
3.2. Domain API Reference 29
Gandi API Client Manual Documentation, Release 2.0-beta
Domain Creation Operation Mapping
An operation struct returned by domain.create().
Domain Information Mapping
A struct returned by domain.info()
name type descriptionid positive integer unique identifierfqdn string fully qualified domain nametld string the top-level domain of your domain nameauthinfo string the authorization tokencontacts struct the contacts associated to the domainnameservers list of string the nameserver list of the domainstatus list of string the domain registry status flag listdate_created datetime when the domain was created (Gandi)date_updated datetime when the domain was last updateddate_registry_creation datetime when the domain was first createddate_registry_end datetime when the domain expirestags list of string the tag listzone string the domain zone name
Note: contacts dictionnary has keys owner, admin, tech, bill
Note: status list can contains TransferProhibited, UpdateOwnerProhibited, ChangeContactProhibited,ChangeDNSProhibited, UpdateServiceProhibited, RenewProhibited, RemoveStatusProhibited, RemoveStatusTrans-ferProhibited flags.
Domain list Information Mapping
A struct returned by domain.list(), this is a subset of the Domain Information Mapping
name type descriptionid positive integer unique identifierfqdn string fully qualified domain nametld string the top-level domain of your domain nameauthinfo string the authorization tokenstatus list of string the domain registry status flag listdate_created datetime when the domain was created (Gandi)date_updated datetime when the domain was last updateddate_registry_creation datetime when the domain was first createddate_registry_end datetime when the domain expires
Domain Renew Mapping
A struct, parameter of domain.renew()
name type descriptionduration positive integer the duration to add to the expiration datecurrent_year positive integer the current year of the expiration date
30 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
Top Level Domains
A struct list returned by domain.tld.list()
name type descriptionregion string the origin region of the tld ( generic for generic purpose )id positive integer a unique identifiername string the tld extension itself ( com, net, ... )
Top Level Domains Folded By Region
A struct returned by domain.tld.region()
name type descriptiongeneric list of string list of available tld extensions for a generic purposeeurope list of string list of available tld extensions from Europeamerica list of string list of available tld extensions from Americaafrica list of string list of available tld extensions from Africaasia list of string list of available tld extensions from Asia
IP List
Parameter of domain.host.create(), domain.host.update()
A list of string representing IPv4 or IPv6 Addresses.
Host Information
A struct returned by domain.host.info()
name type descriptionname string the full qualified domained binding the list of IPips list of string list of IPv4 / IPv6domain string the host domain name
Host list Information
A list of structs returned by domain.host.list()
name type descriptionname string the full qualified domained binding the list of IPips list of string list of IPv4 / IPv6
Domain Transfer Information
A struct, parameter of domain.transferin.proceed()
3.2. Domain API Reference 31
Gandi API Client Manual Documentation, Release 2.0-beta
name type mandatory descriptionowner string mandatory The gandi handle for the owner of the domainadmin string mandatory The gandi handle for the admin contact of the domaintect string mandatory The gandi handle for the technical contact of the domainbill string mandatory The gandi handle for the billing contact of the domainnameservers list mandatory List of nameservers ( string )lang string optional Language in ISO formatauthinfo string optional the authorization tokenchange_owner boolean optional -extra boolean optional -duration boolean optional -
Domain Extra-parameter list
This is the list of the possible domain extra parameters.
name type tld descriptionx-se_ident_number string sex-aero_ens_authid string aero (looks like ENSR-6786)x-aero_ens_authkey string aero a passwordx-pt_legitimacy string pt the legitimacy on registering the respective domain, ie. PC (Corporate Entity) or PS (Individual Entity)x-pt_registrant_vatid string pt owner’s VATx-pt_brand_date isodate pt the date of the trademark’s registration (Format: YYYY-MM-DD)x-pt_brand_number integer pt the trademark number (ex: 22287216)x-pt_registration_basis string pt 6A, 6B, 6F, 6J, 6Kx-pt_brand_way_of_registry string pt INPI, OAMI, or OMPIx-pt_roid string ptx-hk_registrant_document_type string hkx-hk_registrant_document_origin_country isocountry hk country code (FR, GB, US...), ie. the origin of the above docx-hk_registrant_document_number string hkx-hk_registrant_birth_date isodate hkx-hk_registrant_other_document_type string hk mandatory if X-HK-REGISTRANT-DOCUMENT-TYPE is ‘OTHIDV’ or ‘OTHORG’x-ru_registrant_passport_data string ru passeport numberx-it_pin string itx-no_registrant_identity string no The organization number of the Norwegian organization (consisting of exactly 9 digits) CSx-xxx_class enum xxxx-xxx_brand_name string xxxx-xxx_brand_number string xxxx-xxx_brand_class string xxxx-xxx_brand_jurisdiction string xxxx-xxx_brand_country isocountry xxxx-xxx_domain fqdn xxxx-xxx_applied_date isodate xxxx-xxx_registration_date isodate xxxx-xxx_brand_right enum xxxx-xxx_sponsored_community enum xxxx-coop_sponsor string coop Sponsors (to confirm the applicants status as a cooperative)x-ca_legaltype enum ca Legal type, ie. CCO, CCT, RES, GOV, EDU, ASS, HOP, PRT, TDM, TRD, PLT, LAM, TRS, ABO, INB, LGR, OMKx-ca_owner_name string cax-travel_uin string travel Unique Identification Number
32 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
List of alias
Parameter of domain.mailbox.aliases.set()
List of string.
The string represent a local-part of an email. It must not include the domain.
RFC 5322
For domains with an active packmail, leading or trailing wildcards may be used, with at least 2 alphanumericcharacters.For example xyz-* or *.abc
Mailbox Mapping
Returned by domain.mailbox.aliases.set(), domain.mailbox.create(),domain.mailbox.info()
name type descriptionlogin string the login used to access that mailboxfallback_email string email used in case of full quota - currently unusedquota struct granted – int – the allocated quota (in Kio) for this mailbox. 0 if unspecified
used – int – the used quota (in Kio) for this mailbox. 0 if unknownaliases list of str list of aliases on this domain for this mailboxresponder struct active – bool
text – string – responder email contents
Mailbox List Mapping
Returned by domain.mailbox.list()
List of this mapping
name type descriptionlogin string login of the mailbox
Mailbox creation specification
Parameter of domain.mailbox.create()
name type mandatory descriptionpassword string mandatory The password that secure the access to that mailboxfallback_email string optional email used in case of full quota - currently unusedquota int optional the allocated quota (in Kio) if any – 0 if unspecified
Mailbox update specification
Parameter of domain.mailbox.update()
name type mandatory descriptionpassword string optional The password that secure the access to that mailboxfallback_email string optional email used in case of full quota - currently unusedquota int optional the allocated quota (in Kio) if any – 0 if unspecified
3.2. Domain API Reference 33
Gandi API Client Manual Documentation, Release 2.0-beta
Activate Responder specification
Parameter of domain.mailbox.responder.activate()
name type mandatory descriptioncontent string mandatory Textual content of the mail that will be sent as an automatic responsedate datetime optional The activation date should you wish to schedule it in advance
Deactivate Responder specification
Parameter of domain.mailbox.responder.deactivate()
name type mandatory descriptiondate datetime optional The date at which you wish to deactivate the responder. Immediate otherwise
Forward creation specification
Parameter of domain.forward.create(), domain.forward.update()
name type descriptiondestinations list of str list of destinations emails for this forward
Forward Mapping
Returned by domain.forward.list(), domain.forward.create(), domain.forward.update()
name type descriptionsource string the local-part of the email, without the domaindestinations list of str list of destinations emails for this forward
Packmail Information Mapping
Returned by domain.packmail.info()
name type descriptiondomain string the associated domaindate_created - -date_ended - -storage_quota integer -mailbox_quota integer -forward_quota integer -
Packmail create specification
Parameter of domain.packmail.create()
name type mandatory descriptionduration integer mandatory -storage_quota integer mandatory -mailbox_quota integer mandatory -forward_quota integer mandatory -
34 Chapter 3. Gandi Domain API
Gandi API Client Manual Documentation, Release 2.0-beta
Packmail update specification
Parameter of domain.packmail.update()
name type mandatory descriptionstorage_quota integer mandatory -
Packmail renew specification
Parameter of domain.packmail.renew()
name type mandatory descriptionduration integer mandatory -
Packmail autorenew specification
Parameter of domain.packmail.autorenew()
name type mandatory descriptionactive boolean mandatory -duration integer mandatory -
3.3 Domain API FAQ
3.3.1 How-to search and list your domains
Paging results:
>>> api.domain.list(apikey, {’items_per_page’: 10, ’page’: 1})
Sorting results:
>>> api.domain.list(apikey, {’sort_by’ : ’date_end desc’})
Allowed search filters are:
• fqdn
• date_end
• status
• tld
Listing all domains with a fqdn like ‘%mydomain%’:
>>> api.domain.list(apikey, {’~fqdn’: ’%mydomain%’})
Listing all domains with ‘FLN123-GANDI’ as owner:
>>> api.domain.list(apikey, {’owner’: ’FLN123-GANDI’})
Listing all domains with an expiration date after a given date:
>>> api.domain.list(apikey, {’>date_end’ : ’2011-01-01 00:00:00’})
Listing domains by tld:
3.3. Domain API FAQ 35
Gandi API Client Manual Documentation, Release 2.0-beta
>>> api.domain.list(apikey, {’tld’ : ’fr’})
Listing domains by registry status:
>>> api.domain.list(apikey, {’status’ : ’clientTransferProhibited’})
All together:
>>> api.domain.list(apikey, {’items_per_page’: 10,’sort_by’ : ’date_end desc’,’page’: 1,’~fqdn’: ’%mydomain%’,’owner’: ’FLN123-GANDI’,’status’ : ’clientTransferProhibited’,’>date_end’ : ’2011-01-01 00:00:00’})
3.4 Glossary
registry status
• clientTransferProhibited
• clientHold
• clientRenewProhibited
• clientTransferProhibited
• clientUpdateProhibited
• clientDeleteProhibited
3.5 Domain Changelog
Changed in version 2011/11/07: First release of the new Domain API 2.0
36 Chapter 3. Gandi Domain API
CHAPTER
FOUR
GANDI CONTACT API
4.1 Contact API
4.1.1 Introduction
The Gandi Contact API provides a set of remote requests to manage your contacts.
4.1.2 Connect to the API server
The Gandi Contact API is provided through a set of XML-RPC calls. The first step is to connect to the API.
In Python, use the xmlrpclib module from the standard library:
>>> import xmlrpclib>>> api = xmlrpclib.ServerProxy(’https://rpc.gandi.net/xmlrpc/’)>>>>>> # assign your API key to a variable:>>> apikey = ’my 24-character API key’>>>>>> # Now you can call API methods.>>> # You must authenticate yourself by passing the API key as the first method’s argument>>> domains = api.domain.list(apikey)
Note: In Python 3 xmlrpclib has been renamed xmlrpc.client
In PHP 5, with the XML_RPC2 package from pear:
<?php// Library installed from PEARrequire_once ’XML/RPC2/Client.php’;
// The first step is to connect to the API$domain_api = XML_RPC2_Client::create(
’https://rpc.gandi.net/xmlrpc/’,array( ’prefix’ => ’domain.’ )
);
// assign your API key to a variable$apikey = ’my 24-character API key’;
// Now you can call API method
37
Gandi API Client Manual Documentation, Release 2.0-beta
// You must authenticate yourself by passing the API key as the first method’s argument$result = $domain_api->list($apikey);
// dump the resultprint_r($result);?>
Note: XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have toinstanciante a client by namespace
With NodeJS, use the xmlrpc package from npm:
> var xmlrpc = require(’xmlrpc’)> var api = xmlrpc.createSecureClient({... host: ’rpc.gandi.net’,... port: 443,... path: ’/xmlrpc/’... })>> //Assign your API key to a variable> var apikey = ’my 24-character API key’>> // Now you can call API methods.> // You must authenticate yourself by passing the API key as the first method’s argument> api.methodCall(’domain.list’, [apikey], function (error, value) {... console.dir(value)... })
use XML::RPC;
my $api = XML::RPC->new(’https://rpc.gandi.net/xmlrpc/’);
# assign your API key to a variable:my $apikey = ’my 24-character API key’;
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentmy $domains = $api->call( ’domain.list’, $apikey );
require ’xmlrpc/client’
server = XMLRPC::Client.new2(’https://rpc.gandi.net/xmlrpc/’)
# assign your API key to a variable:apikey = ’my 24-character API key’
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentdomains = server.call("domain.list", apikey)
Note: Store the API key in a safe place.
38 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
4.1.3 Contact Management
Get information
Listing your contacts or the contacts related to you:
>>> contacts = api.contact.list(apikey)
Getting your information:
>>> contact = api.contact.info(apikey)
Or information of a contact related to you:
>>> contact = api.contact.info(apikey, contacts[1][’handle’])
Note: the output of contact.list() and contact.info() will vary according to your relationship with thecontact(s).
Create a contact
To create a contact use the contact.create() method by specifying, at least, given and family names, email,address, phone, the type (0, for a particular, 1 for a company, 2 for an association, 3 for a public body) and thepassword of your contact:
>>> contact_spec = {... ’given’: ’First Name’,... ’family’: ’Last Name’,... ’email’: ’[email protected]’,... ’streetaddr’: ’My Street Address’,... ’zip’: ’75011’,... ’city’: ’Paris’,... ’country’: ’FR’,... ’phone’:’+33.123456789’,... ’type’: 0,... ’password’: ’xxxxxxxx’}>>> contact = api.contact.create(apikey, contact_spec)>>> contact[’handle’]’FLN123-GANDI’
Update a contact
To update a contact use the contact.update() method:
>>> handle = api.contact.info(apikey)[’handle’]>>> contact_spec = {
....: ’streetaddr’: ’My New Street Address’,
....: ’zip’: ’75012’}>>> contact = api.contact.update(apikey, handle, contact_spec)
4.1. Contact API 39
Gandi API Client Manual Documentation, Release 2.0-beta
4.2 Contact API Reference
4.2.1 contact
Contact API
contact.can_associate(apikey, contact, domain)Test if a contact (full contact description) can be associated to the domains.
Parameters
• apikey (struct) – the user identification.
• contact (struct) – the contact details.
• domain (struct) – the domain(s) the user want to create.
Returns boolean – true if the contact can be associated to the domain
contact.can_associate_domain(apikey, handle, domain)Test if a contact (defined by it’s handle) can create that domain.
Parameters
• apikey (struct) – the user identification.
• handle – the contact handler (needs to be change from String to something that does
more checks on the handle). :type handle: struct
Parameters domain (struct) – the domain(s) the user want to create.
Returns boolean – true if the contact can be associated to the domain
contact.create(apikey, contact)Should have a all optional contact dict then look if he is a person or a company and depending on that callcreate_person or create_company.
Parameters
• apikey (struct) – the user identification.
• contact (struct) – the contact details.
Returns struct – the contact in detail if correctly created
contact.info(apikey[, handle=’‘])Give all information on the given contact.
Parameters
• apikey (struct) – the user identification.
• handle – the contact handler (needs to be change from String to something that does
more checks on the handle). :type handle: struct :returns: struct – the contact in detail
contact.list(apikey[, opts=nil])List all contacts linked to the connected user (it will only return contacts when the apikey belong to a reseller).
Parameters
• apikey (string) – the user identification.
• opts – optional parameter to filter list result Recognised keys are: filter,
offset, limit, order, group. :type opts: struct :returns: list of struct – list of contact info dicts
40 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
contact.update(apikey, handle, contact)Check the same way as check and then update.
Parameters
• apikey (struct) – the user identification.
• handle – the contact to update handler (needs to be change from String to something
that does more checks on the handle). :type handle: struct
Parameters contact (struct) – the contact details.
Returns struct – the contact in detail if correctly updated
4.2.2 Mappings
contact type
id description0 person1 company2 association3 organization4 reseller
Extra Parameters
Takes all the Domain Extra-parameter list plus thoses one:
name type mandatory descriptionbirth_city string optional city of birthbirth_department string optional department codebirth_date date optional birth datebirth_country string optional birth iso country codeduns string optional company duns numberwaldec string optional association waldec numbermarque string optional company/association/person trademark
Contact Information
Returned by contact.info() or contact.create():
4.2. Contact API Reference 41
Gandi API Client Manual Documentation, Release 2.0-beta
name type descriptionid positive integer unique identifierhandle string the contact Gandi Handletype integer the contact type contact typeorgname string the contact organization namegiven string the contact given namefamily string the contact family namestreetaddr string the contact street addresscity string the contact citystate string the contact statezip string the contact zipcountry string the contact iso country codephone string the contact phone numberfax string the contact fax numbermobile string the contact mobile numbertva_number string the contact tva numbersiren string the contact siren/siretmarque string the contact marquelang string the contact preferred languagenewsletter integer whether or not the contact subscribes to GANDI newsletterobfuscated integer whether or not the contact information is private in the public databaseswhois_obfuscated integer whether or not the contact information is private in the public databasesresell boolean whether or not the contact information might be sold to any party that requests itshippingaddress dictionnary the contact ahipping addressextra_parameters dictionnary the contact extra information contact extra parameters
Note: extra_parameters describes specific extra information requested by registries. See Extra Parameters for a fulldescription of these parameters
Note: the fields you are going to see depend on the permissions you have on that contact.
Note: available languages are ‘FR’ for French, ‘EN’ for English, ‘ES’ for Spanish
Contact Parameters
Parameter of contact.create():
42 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
name type manda-tory
description
type positiveinteger
manda-tory
contact type
given string manda-tory
given name
family string manda-tory
family name
password string manda-tory
password
email string manda-tory
email address
phone string manda-tory
phone number
streetaddr string manda-tory
street address
city string manda-tory
city
zip string manda-tory
zip code
country string manda-tory
iso format country code
orgname string optional organisationstate string optional state codefax string optional fax numbermobile string optional mobile numbernewsletter boolean optional subscribe to newsletterobfuscated boolean optional -lang string optional preferred language ( en, fr or es )jo_announce_page int optional -jo_announce_number int optional -jo_declaration_date date optional -jo_publication_date date optional -tva_number string optional -siren string optional siren ot siret numbermarque string optional -extra_parameters struct optional extra parameterssecu-rity_question_num
int optional the security question number
secu-rity_question_answer
string optional answer to the security question
whois_obfuscated boolean optional obfuscate whois dataresell boolean optional whether or not the contact information might be sold to any
party that requests it
Note: security_question_num values are
• 1 “What is the name of your favorite city?”
• 2 “What is your mother’s maiden name?”
• 3 “What is your favorite food?”
• 4 “What year were you born in?”
• 5 “What is your cell phone number?”
4.2. Contact API Reference 43
Gandi API Client Manual Documentation, Release 2.0-beta
• 6 “In what year was your Gandi account created?”
Domain Association Parameters
Parameter of contact.can_associate() and contact.can_associate_domain():
name type mandatory descriptiondomain string mandatory the domain nameowner boolean optional if true check owner associationadmin boolean optional if true check admin associationtech boolean optional if true check tech associationbill boolean optional if true check bill association
4.3 Contact API FAQ
4.3.1 How-to search and list your contacts
Paging results:
>>> api.contact.list(apikey, {’items_per_page’: 10, ’page’: 1})
Sorting results:
>>> api.contact.list(apikey, {’sort_by’ : ’handle desc’})
Allowed search filters are:
• handle
• orgname
• given
• family
• type
• zip
• city
• streetaddr
• country
Listing all contacts with a email like ‘%mydomain%’:
>>> api.contact.list(apikey, {’~email’: ’%mydomain%’})
Listing contacts by type:
>>> api.contact.list(apikey, {’type’: 0})
All together:
44 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
>>> api.contact.list(apikey, {’items_per_page’: 10,’sort_by’ : ’handle desc’,’page’: 1,’type’: 0,})
4.3.2 How-to check domain/contact association
The Contact API can_associate_domain() and can_associate() allow you to check the domain avail-ability for a given contact (in a context of a contact registering, transferring, or updating the domain process).
Example: checking mydomain.fr availability for FLN123-GANDI, as admin and owner contact
>>> association_spec = {... ’domain’: ’mydomain.fr’,... ’owner’: True,... ’admin’: True}>>> api.contact.can_associate_domain(apikey, ’FLN123-GANDI’, association_spec)True>>> res = api.contact.can_associate_domain(apikey, ’FLN123-GANDI’, association_spec)>>> [(x[’field’], x[’field_type’], x[’error’], x[’reason’]) for x in res][(’birth_city’,
’String’,’EC_INVALIDPARAM1+EC_STRTOOFEWCHARS’,"BirthCity: string ’’ has less than 1 characters"),
(’birth_date’,’Date’,’EC_INTERNALERR2’,"BirthDate: time data ’’ does not match format ’%Y-%m-%d’"),
(’birth_department’,’String’,’EC_INVALIDPARAM1+!EC_STRMATCH’,"BirthDepartment: string ’’ does not match ’^(2A|2B|\\d{1,3})$’"),
(’birth_country’,’Enum’,’EC_INVALIDPARAM1+!EC_ENUMIN’,’BirthCountryIso: not in list AF,ZA,AL,DZ,DE,AD,AO,AI,AG,AN,SA,AR,AM,AW,AC,AU,AT,AZ,BS,BH,BD,BB,BY,BE,BZ,BJ,BM,BT,BO,BA,BW,BR,BN,BG,BF,BI,KH,CM,CA,CV,KY,CF,CL,CN,CY,CO,KM,CG,CD,CK,KR,KP,CR,CI,HR,CU,DK,DJ,DO,DM,EG,SV,AE,EC,ER,ES,EE,US,ET,FK,FO,FJ,FI,FR,GA,GM,GE,GH,GI,GR,GD,GL,GU,GT,GN,GQ,GW,GY,HT,HI,HN,HK,HU,IN,ID,IR,IQ,IE,IS,IL,IT,JM,JP,JE,JO,KZ,KE,KG,KI,KW,LA,LS,LV,LB,LR,LY,LI,LT,LU,MO,MK,MG,MY,MW,MV,ML,MT,MP,MA,MH,MU,MR,MX,FM,MD,MC,MN,MS,MZ,MM,NA,NR,NP,NI,NE,NG,NU,NF,NO,NZ,OM,UG,UZ,PK,PW,PS,PA,PG,PY,NL,PE,PH,PL,PT,PR,QA,RO,GB,RU,RW,SH,LC,KN,SM,VC,SB,AS,WS,ST,SN,SC,SL,SG,SK,SI,SO,SD,LK,SE,CH,SR,SZ,SY,TJ,TW,TZ,TD,CZ,TH,TP,TG,TK,TO,TT,TN,TM,TC,TR,TV,UA,UY,VU,VE,VI,VG,VN,YE,ZM,ZW,RE,PF,AQ,GF,NC,MQ,GP,PM,TF,YT,RS,TL,CC,CX,HM,AX,BV,GS,GG,IM,ME,IO,PN,EH,BL,MF,VA,SJ,WF,EP’)]
<?php$contact_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’contact.’));$association_spec = array(
’domain’ => ’mydomain.fr’,’owner’ => true,’admin’ => true );
print_r( $contact_api->can_associate_domain($apikey, ’GG2647-GANDI’, $association_spec) );// 1// ORprint_r( $contact_api->can_associate_domain($apikey, ’FLN123-GANDI’, $association_spec) )/*[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,
’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...
},... ]
*/?>
4.3. Contact API FAQ 45
Gandi API Client Manual Documentation, Release 2.0-beta
> var association_spec = {... domain: ’mydomain.fr’,... owner: true,... admin: true}> api.methodCall(’contact.can_associate_domain’,... [apikey, ’FLN123-GANDI’, association_spec],... function (error, value) {... console.dir(value)... })
my $association_spec = {’domain’ => ’mydomain.fr’,’owner’ => True,’admin’ => True
};my $result = $api->call( ’contact.can_associate_domain’, $apikey, ’FLN123-GANDI’, $association_spec );print $result;True$result = $api->call( ’contact.can_associate_domain’, $apikey, ’FLN123-GANDI’, $association_spec );print $result;[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]
association_spec = {’domain’ => ’mydomain.fr’,’owner’=> true,’admin’=> true
}print server.call("contact.can_associate_domain", apikey, ’FLN123-GANDI’, association_spec)Trueprint server.call("contact.can_associate_domain", apikey, ’FLN123-GANDI’, association_spec)[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]
In this example, birth_city, birth_date, birth_department and birth_country are missing or invalid contact attributes.
For each field, the method returns various information like the field type, the error type and the reason why it isincorrect (see error codes for a complete description of error types).
To modify your contact use the contact.update() method:
>>> contact_spec = {’extra_parameters’: {’birth_city’: ’Paris’,’birth_date’: ’1980-01-01’,’birth_department’: ’75’,’birth_country’: ’FR’}}
>>> operation = api.contact.update(apikey, ’FLN123-GANDI’, contact_spec)>>> api.operation.info(apikey, operation[’id’])[’step’]’DONE’>>> api.contact.can_associate_domain(apikey, ’FLN123-GANDI’, association_spec)True
46 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
<?php$contact_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’contact.’));$contact_spec = array(’extra_parameters’ => array(’birth_city’ => ’Paris’,’birth_date’ => ’1980-01-01’,’birth_department’ => ’75’,’birth_country’=> ’FR’ ));
$operation = $contact_api->update($apikey, ’FLN123-GANDI’, $contact_spec) ;$operation_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’operation.’));print_r ( operation_api->info($apikey, $operation[’id’]) );// ’DONE’print_r( $contact_api->can_associate_domain($apikey, $association_spec) );// 1?>
> var contact_spec = {extra_parameters: {birth_city: ’Paris’,birth_date: ’1980-01-01’,birth_department: ’75’,birth_country: ’FR’}}
> api.methodCall(’contact.update’,[apikey, ’FLN123-GANDI’, contact_spec],function (error, value) {
console.dir(value)})
my $contact_spec = {’extra_parameters’ => {’birth_city’ => ’Paris’,’birth_date’ => ’1980-01-01’,’birth_department’ => ’75’,’birth_country’=> ’FR’
}};
my $operation = $api->call( ’contact.update’, $apikey, ’FLN123-GANDI’, $contact_spec );$operation = $api->call( ’operation.info’, $apikey, $operation->{id} );print $operation->{step};’DONE’my $result = $api->call( ’contact.can_associate_domain’, $apikey, $association_spec );print $result;1
contact_spec = {’extra_parameters’ => {’birth_city’ => ’Paris’,’birth_date’ => ’1980-01-01’,’birth_department’ => ’75’,’birth_country’=> ’FR’
}}
operation = server.call("contact.update", apikey, ’FLN123-GANDI’, contact_spec)operation = server.call("operation.info", apikey, operation{’id’})print operation[’step’]’DONE’
4.3. Contact API FAQ 47
Gandi API Client Manual Documentation, Release 2.0-beta
result = server.call("contact.can_associate_domain", association_spec)print resulttrue
The contact.can_associate() method allows you to check domain/contact association rules according tocontact specifications:
>>> association_spec = {... ’domain’: ’mydomain.fr’,... ’owner’: True,... ’admin’: True}>>> contact_spec = {... ’type’: 0,... ’given’: ’Given’,... ’family’: ’Family’,... ’password’: ’PassworD’,... ’email’: ’[email protected]’,... ’phone’: ’+33123456789’,... ’streetaddr’: ’my street’,... ’city’: ’My City’,... ’zip’: ’75000’,... ’country’: ’FR’}>>> api.contact.can_associate(apikey, contact_spec, association_spec)[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]>>> api.contact.can_associate(apikey, contact_spec, association_spec)True
<?php$contact_api = XML_RPC2_Client::create($api_uri, array(’prefix’ => ’contact.’));$association_spec = array(
’domain’ => ’mydomain.fr’,’owner’ => true,’admin’ => true );
$contact_spec = array(’type’ => 0,’given’ => ’Given’,’family’ => ’Family’,’password’ => ’PassworD’,’email’ => ’[email protected]’,’phone’ => ’+33123456789’,’streetaddr’ => ’my street’,’city’ => ’My City’,’zip’ => ’75000’,’country’ => ’FR’ );
print_r( $contact_api->can_associate($apikey, $contact_spec, $association_spec) );// 1// ORprint_r( $contact_api->can_associate($apikey, $contact_spec, $association_spec) )/*[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,
’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...
},... ]
*/
48 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
?>
> var association_spec = {... domain: ’mydomain.fr’,... owner: true,... admin: true}> var contact_spec = {... type: 0,... given: ’Given’,... family: ’Family’,... password: ’PassworD’,... email: ’[email protected]’,... phone: ’+33123456789’,... streetaddr: ’my street’,... city: ’My City’,... zip: ’75000’,... country: ’FR’}> api.methodCall(’contact.can_associate’,... [apikey, contact_spec, association_spec],... function (error, value) {... console.dir(value)... })
my $association_spec = {domain => ’mydomain.fr’,owner => True,admin => True
};my $contact_spec = {
type => 0,given => ’Given’,family => ’Family’,password => ’PassworD’,email => ’[email protected]’,phone => ’+33123456789’,streetaddr => ’my street’,city => ’My City’,zip => ’75000’,country => ’FR’
};
my $result = $api->call( ’contact.can_associate’, $apikey, $contact_spec, $association_spec );print $result;[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]my $result = $api->call( ’contact.can_associate’, $apikey, $contact_spec, $association_spec );print $result;True
association_spec = {’domain’ => ’mydomain.fr’,’owner’=> true,’admin’=> true
}contact_spec = {
4.3. Contact API FAQ 49
Gandi API Client Manual Documentation, Release 2.0-beta
’type’ => 0,’given’ => ’Given’,’family’ => ’Family’,’password’ => ’PassworD’,’email’ => ’[email protected]’,’phone’ => ’+33123456789’,’streetaddr’ => ’my street’,’city’ => ’My City’,’zip’ => ’75000’,’country’ => ’FR’
}
print server.call("contact.can_associate", apikey, contact_spec, association_spec)[{’error’: ’EC_INVALIDPARAM1+!EC_ENUMIN’,’field’: ’birth_country’,’field_type’: ’Enum’,’reason’: ’BirthCountryIso: not in list ...},... ]print server.call("contact.can_associate", apikey, contact_spec, association_spec)True
4.4 Glossary
error codes Error codes can be concatenated with + and can be prefixed with ! if negative. Some error codes aremainly used in their negative form (like EC_OLDENOUGH for exemple)
exceptions
error code descriptionEC_CANASSOCIATE The contact can’t be associated to that tldEC_INVALIDPARAM1EC_INVALIDPARAM2EC_INVALIDPARAM3
parameters
error code descriptionEC_STRTOOFEWCHARS The string is too shortEC_STRTOOMANYCHARS The string is too longEC_STRLENCHARS The string is the right sizeEC_STRTOOFEWWORDS The string contains too few wordsEC_STRTOOMANYWORDS The string contains too many wordsEC_STRLENWORDS The string contains the right number of wordsEC_STRMATCH The string matches the regexpEC_ENUMIN The value is in the list of possible valuesEC_INTLOWER The integer is too smallEC_INTGREATER The integer is too bigEC_FLOATLOWER The float is too smallEC_FLOATGREATER The float is too bigEC_MULTIPLE The value is a multipleEC_VALIDAPIKEY The api key is validEC_VALIDBOOL The bool is validEC_MISSINGFIELD One field is missingEC_MISSINGFIELDS Several fields are missing
Continued on next page
50 Chapter 4. Gandi Contact API
Gandi API Client Manual Documentation, Release 2.0-beta
Table 4.1 – continued from previous pageEC_MISSINGMANDATORY One mandatory field is missingEC_MISSINGMANDATORIES Several mandatory fields are missingEC_UNKNOWNFIELD The field is unknownEC_LISTTOOFEW The list contains too few elementsEC_LISTTOOMANY The list contains too many elementsEC_LISTDUPLICATE The list contains duplicatesEC_VALIDDATE The date has a valid formatEC_VALIDTIME The time has a valid formatEC_VALIDDATETIME The datetime has a valid formatEC_OLDENOUGH The contact is old enoughEC_VALIDSIREN The siren has a valid formatEC_VALIDSIRET The siret has a valid formatEC_VALIDDOMAIN The domain has a valid formatEC_VALIDPASSWORD The password has a valid formatEC_FIELDEQUAL The two fields are equalEC_FIELDUPDATEPOSSIBLE The field can’t be updatedEC_FORBIDENCONTACTTYPE This contact type is forbiddenEC_CLOSEDTLD This tld is closedEC_OPENTLD This tld is open to everyoneEC_NORULETLD This tld has no validation ruleEC_TLDNEEDSAMECONTACT This tld needs the same contact at different rolesEC_OUTOFCONTEXT The rule does not apply in that contextEC_NOTAHANDLE This should be a gandi handle
4.4. Glossary 51
CHAPTER
FIVE
GANDI HOSTING API
5.1 Hosting API
5.1.1 Introduction
The Gandi Hosting API provides a set of remote requests to manage your hosting resources. You can manage resourcesin all datacenters from all API locations.
5.1.2 Connect to the API server
The Gandi Hosting API is provided through a set of XML-RPC calls.
In Python, use the xmlrpclib module from the standard library:
>>> import xmlrpclib>>> api = xmlrpclib.ServerProxy(’https://rpc.gandi.net/xmlrpc/’)>>>>>> # assign your API key to a variable:>>> apikey = ’my 24-character API key’>>>>>> # Now you can call API methods.>>> # You must authenticate yourself by passing the API key as the first method’s argument>>> domains = api.domain.list(apikey)
Note: In Python 3 xmlrpclib has been renamed xmlrpc.client
In PHP 5, with the XML_RPC2 package from pear:
<?php// Library installed from PEARrequire_once ’XML/RPC2/Client.php’;
// The first step is to connect to the API$domain_api = XML_RPC2_Client::create(
’https://rpc.gandi.net/xmlrpc/’,array( ’prefix’ => ’domain.’ )
);
// assign your API key to a variable$apikey = ’my 24-character API key’;
53
Gandi API Client Manual Documentation, Release 2.0-beta
// Now you can call API method// You must authenticate yourself by passing the API key as the first method’s argument$result = $domain_api->list($apikey);
// dump the resultprint_r($result);?>
Note: XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have toinstanciante a client by namespace
With NodeJS, use the xmlrpc package from npm:
> var xmlrpc = require(’xmlrpc’)> var api = xmlrpc.createSecureClient({... host: ’rpc.gandi.net’,... port: 443,... path: ’/xmlrpc/’... })>> //Assign your API key to a variable> var apikey = ’my 24-character API key’>> // Now you can call API methods.> // You must authenticate yourself by passing the API key as the first method’s argument> api.methodCall(’domain.list’, [apikey], function (error, value) {... console.dir(value)... })
use XML::RPC;
my $api = XML::RPC->new(’https://rpc.gandi.net/xmlrpc/’);
# assign your API key to a variable:my $apikey = ’my 24-character API key’;
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentmy $domains = $api->call( ’domain.list’, $apikey );
require ’xmlrpc/client’
server = XMLRPC::Client.new2(’https://rpc.gandi.net/xmlrpc/’)
# assign your API key to a variable:apikey = ’my 24-character API key’
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentdomains = server.call("domain.list", apikey)
Note: Store the API key in a safe place.
54 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
5.1.3 Virtual Machine Management
Steps to create a VM
1. Check available resources
2. Choose a datacenter
3. Choose an operating system image
4. Create the VM
Gandi Hosting provides resource management in the cloud. The main resource is the virtual machine (VM). You canattach disks, and network interfaces to a VM.
Note: The Hosting API only manages resources. Billing is managed in the web management interface. It means youmust have enough shares to create or add a resource.
Check available resources
You can check you have enough quota with account.info():
>>> account = api.account.info(apikey)
Now account holds information about your account and the status of your resources:
>>> account[’resources’][’available’]{’available’: {’bandwidth’: 40960.0,
’cores’: 3,’disk’: 73728,’ips’: 0,’memory’: 2048,’shares’: 8}}
To create a VM you need at least one share. You may want to map a description in terms of memory, disk andbandwidth to shares. The following configuration, in YAML format, describes a VM:
datacenter: Francehostname: vm_example0memory: 512disks:
- size: 12288name: vm_example0_data0
- size: 6144name: vm_example0_data1
ifaces:bandwidth: 5120reverse: ’vm_example.example.net’
Let translate it to a Python data structure:
>>> import yaml>>> myvm_description = yaml.load(file(’myvm.yaml’))>>> myvm_description{’datacenter’: ’France’,’disks’: [{’name’: ’vm_example0_data0’, ’size’: 4096},
{’name’: ’vm_example0_data1’, ’size’: 2096}],’hostname’: ’vm_example0’,
5.1. Hosting API 55
Gandi API Client Manual Documentation, Release 2.0-beta
’ifaces’: {’bandwidth’: 5120, ’reverse’: ’vm_example.example.net’},’memory’: 512}
Now define share_def :
>>> share_def = api.account.info(apikey)[’share_definition’]>>> share_def{’bandwidth’: 5120.0, ’cores’: 0.25, ’disk’: 8192, ’memory’: 256, ’servers’: 1}
This defines a share with grants of 256MB of memory, 8192MB (8MB) of disk, and 5120Kbps (5Mbps) of bandwidth,0.25 core, and also 1 server possibly creatable. We want to create a VM with 512MB of memory, two disks with atotal of 18432, and one network interface of 5120Kbps. Calculate memory first.
Two shares bring:
• 512MB of memory
• 16384MB of disk
• 10240Kbps of bandwidth
• 0.5 of core
• 2 creatable servers
We have twice the required bandwidth and lacks 2048MB of disk. Then we check if we have enough available diskquota in our account:
>>> account[’resources’][’available’][’disk’]73728
Consequently we can create a VM from this configuration file. We can go further and actually create the VM.
Choose a datacenter
Gandi hosts servers in multiple datacenters. At first you need to choose where you resources will be:
>>> api.datacenter.list(apikey)[{’country’: ’France’,
’id’: 1,’iso’: ’FR’,’name’: ’Equinix Paris’},
{’country’: ’United States of America’,’id’: 2,’iso’: ’US’,’name’: ’Level3 Baltimore’}]
You can automate this by retrieving the datacenter’s country from the configuration file:
>>> fr_datacenters = [dc for dc in api.datacenter.list(apikey)... if dc[’country’].lower() == myvm_description[’datacenter’].lower()]>>> fr_datacenters[{’country’: ’France’, ’id’: 1, ’iso’: ’FR’, ’name’: ’Equinix Paris’}]>>> dc_id = fr_datacenters[0][’id’]
Choose an operating system image
Before you create a VM, you need to choose the disk image with the OS you want. Lets imagine you want to create aVM with an Ubuntu image:
56 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
>>> images = api.image.list(apikey, {’datacenter_id’: 1})>>> ubuntu_images = [x for x in images if x[’label’].lower().startswith(’ubuntu’)]>>> ubuntu_images[{’author_id’: 248842,
’datacenter_id’: 1,’date_created’: <DateTime ’20100101T00:00:00’ at 25cd248>,’date_updated’: <DateTime ’20101007T06:43:17’ at 25cd200>,’disk_id’: 43024,’id’: 15,’label’: ’Ubuntu 9.10’,’os_arch’: ’x86-32’,’visibility’: ’all’},
{’author_id’: 248842,’datacenter_id’: 1,’date_created’: <DateTime ’20100101T00:00:00’ at 25cd2d8>,’date_updated’: <DateTime ’20101007T06:43:17’ at 25cd290>,’disk_id’: 45512,’id’: 16,’label’: ’Ubuntu 9.10 + ispCP’,’os_arch’: ’x86-32’,’visibility’: ’alpha’},
{’author_id’: 248842,’datacenter_id’: 1,’date_created’: <DateTime ’20100101T00:00:00’ at 25cd368>,’date_updated’: <DateTime ’20101007T06:43:17’ at 25cd320>,’disk_id’: 49300,’id’: 17,’label’: ’Ubuntu 9.10 + Cherokee’,’os_arch’: ’x86-32’,’visibility’: ’all’},
{’author_id’: 248842,’datacenter_id’: 1,’date_created’: <DateTime ’20100101T00:00:00’ at 25cd3f8>,’date_updated’: <DateTime ’20101007T06:43:17’ at 25cd3b0>,’disk_id’: 51848,’id’: 18,’label’: ’Ubuntu 10.04’,’os_arch’: ’x86-32’,’visibility’: ’all’}]
It will return the list of all images with a name like (‘~’) ubuntu (case-insensitive). You can filter the list for the version:
>>> filter(lambda x: ’10.04’ in x[’label’], ubuntu_images)[{’author_id’: 248842,
’datacenter_id’: 1,’date_created’: <DateTime ’20100101T00:00:00’ at 25cd3f8>,’date_updated’: <DateTime ’20101007T06:43:17’ at 25cd3b0>,’disk_id’: 51848,’id’: 18,’label’: ’Ubuntu 10.04’,’os_arch’: ’x86-32’,’visibility’: ’all’}]
Let take the disk associated with this image to create our VM:
5.1. Hosting API 57
Gandi API Client Manual Documentation, Release 2.0-beta
>>> src_disk_id = 18
Create the VM
Create the VM from a vm_spec mapping with vm.create_from():
>>> disk_spec = {’datacenter_id’: dc_id,’name’: ’disk_%s’ % myvm_description[’hostname’]}
>>> vm_spec = {’datacenter_id’:dc_id,’hostname’: myvm_description[’hostname’],’password’: ’password_to_change’,’memory’: myvm_description[’memory’],’cores’: 1}
>>> op = api.vm.create_from(apikey, vm_spec, disk_spec, src_disk_id)
vm.create_from() takes the VM specification as its second argument, the disk specification as its third, andfinally the source disk id. Behind the scenes, the Gandi backend creates a new disk from the source disk. When youask Gandi to create a VM, the VM is not immediately available. It will start to work in Gandi’s backend to prepare theenvironment of the VM. This work is tracked with the Operation.
You can poll the operation status by calling operation.info():
>>> op = api.operation.info(apikey, op[’id’])>>> vm_id = op[’vm_id’]
In the example, we will call operation_wait() to represent a function that wait until the operation is done.
Note: in order to boot, a VM will use the cmdline defined with its first disk. With a linux disk image, cmdlinemay contain root=/dev/xvda1. This means the kernel will mount the first partition of the first disk as the rootfilesystem.
The process of VM creation will automatically create a network interface. When creating a network interface, thesystem tries to recycle an IP. If you have already released an IP, the next IP creation will get this old IP.
After the creation, the VM is automatically started.
Log into a VM
Once the VM has successfully started you can log in:
$ ssh user@vm_ip<enter password from vm_spec passed to vm.create>
Note: You may want to add an SSH public key for some users in ~<user>/.ssh/authorized_keys . Please refer to thesystem administration and security manual of the operation system distribution.
Update a VM
The VM is running and you want to increase its memory:
58 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
>>> op = api.vm.update(apikey, vm[’id’], {’memory’: 1024})
The following VM attributes can be updated:
• hostname: a Unicode string up to 63 characters
• memory: by step of 256MB between 256MB and 4096MB
• vm_max_memory: 2048MB, 4096MB, 6144MB
• cores
The state is managed by vm.start(), vm.reboot(), and vm.stop().
Note: vm_max_memory is used to limit the memory reserved by xen to manage memory allocation on the guest. Itis an implementation-specific attribute we need to expose to the user. In practice, it defines the maximum memory theVM can manage. When a VM is created with less than 2048MB of memory, vm_max_memory is equal to 2048MB. Ifyou want to increase memory beyond this limit you need to update vm_max_memory and reboot the VM.
5.2 Hosting Changelog
Changed in version 2011/09/19: add a hosting top level namespace.(eg: ip -> hosting.ip, vm -> hosting.vm,... )Changed in version 2010/10/25: Uses of XMLRPC extension to allow returning “nil”.Changed in version2010/10/25: iface.list() now returns ips_id instead of ips (see iface-return)Changed in version 2010/10/26:disk.update() now raises if trying to shrink the diskChanged in version 2010/10/26: vm.create()and vm.create_from(): the password parameter is now mandatory (vm-create-spec and vm-create-from-spec)Changed in version 2010/10/27: operation.info() now really returns a mapping, instead of a se-quenceChanged in version 2010/10/28: ip.list() accepts iface_id and num filterChanged in version 2010/10/28:ip.list() and ip.info() now returns the num attribute (see ip-return)Changed in version 2010/10/28: Theversion (see ip-return) attribute returned by ip.list() and ip.info() is now an integer, to stick with theip_version attribute which is an integerChanged in version 2010/11/26: The state (see ip-return) attribute changed:being_created or created instead of free or usedChanged in version 2010/11/29: shares is now depre-cated, and will be soon unavailable. You will have to manually manage cores and bandwidth instead of shares(see vm-return, vm-create-spec, vm-create-from-spec). shares will be totally removed at the end of the beta pe-riod.Changed in version 2010/11/29: Maximun amount of memory for a VM is now 12GB (see VM Update, vm-create-from-spec, vm-create-spec, vm-return)Changed in version 2010/12/06: Removed disk.get_options(), replacedby disk.list_kernels() and disk.list_options()Changed in version 2010/12/15: Added the ‘iso’attribute in datacenter.list() (see dc-return)Changed in version 2011/01/20: disk.list_kernels()now takes an additional datacenter_id parameterChanged in version 2011/01/27: Fixed a typo, the maximunnumber of allowed cores per VM is 6, not 8Changed in version 2011/02/16: The parameter datacenter_idis now optional in disk.create_from() (see disk-create-from)Changed in version 2011/05/04: Documentsdisk.rollback_from() and vm.disk_rollback()
5.3 Hosting API Reference
5.3.1 Common Interface
Overview
A server is represented by a virtual machine with the object vm. A vm object contains:
• disks
5.2. Hosting Changelog 59
Gandi API Client Manual Documentation, Release 2.0-beta
• network interfaces
Attributes Conventions
If not specified attributes respect the following conventions:
• id or *_id: unique positive integer
• datacenter_id: unique positive integer
• name: unicode string
• description: unicode string
• signature: cryptographic hash or pgp signature?
5.3.2 Datacenter API Reference
hosting.datacenter
Datacenter API Interface.hosting.datacenter is an informal namespace, you can’t modify it.
hosting.datacenter.list(apikey[, filtering=nil])
List available datacenters.Available filters are:
•id.
Parameters
• apikey (string) – the user identification.
• filtering (struct) – Filter list result (see Filters).
Returns struct – list a datacenter descriptions
Mappings
Datacenter Mapping
Returned by hosting.datacenter.list()
name values descriptionid positive integer unique identifiername string name of the datacentercountry string name of the country were the datacenter isiso string iso code of the country
60 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
5.3.3 Disk Image API Reference
hosting.image
API Disk Image inteface.
Describes a system image with an operating system. It is associated with a disk that stores the filesystem.
hosting.image is an informal namespace, you can’t modify it.
hosting.image.info(apikey, image_id)Get information about the disk image.
Parameters
• apikey (string) – the user apikey.
• image_id (int) – the image id.
Returns struct – the disk image information
hosting.image.list(apikey[, opts=nil])Get the list of available disk images.
Parameters
• apikey (string) – the user apikey.
• opts (struct) – optional parameter to filter list result (see Filters).
Returns list of struct – a list of images
Mappings
name values descriptionid positive integer unique identifierlabel string name of the operating systemdatacenter_id positive integer location of the resourcedisk_id positive integer id of the disk to use as a sourcevisibility public | private | alpha who can access this imageos_arch x86-32 | x86-64 CPU architecture this image is made forauthor_id positive integer who is the author of this image
5.3.4 Disk API Reference
hosting.disk
Disk API Interface.A disk represents a virtual storage device.
hosting.disk.count(apikey[, filtering=nil])Count the number of disks.
Available filters are:
•id
•datacenter_id
5.3. Hosting API Reference 61
Gandi API Client Manual Documentation, Release 2.0-beta
•name
•size
•state
•type
•vm_id.
Parameters
• apikey (string) – user identification key.
• filtering (struct) – optional parameter to filter results (see Filters).
Returns int – number of disks matching the filter
hosting.disk.create(apikey, disk_spec)
Create an empty disk with respect to the attributes specified by disk_spec.It checks the available quota.
Parameters
• apikey (string) – user identification key.
• disk_spec (struct) – specification of the disk to create.
Returns struct – a disk_create Operation
hosting.disk.create_from(apikey, disk_spec, src_disk_id)
Create a disk with the same data as the disk identified by src_disk_id.kernel_id, kernel_cmdline, size, and label will
be copied from the source disk.
Parameters
• apikey (string) – user identification key.
• disk_spec (struct) – specification of the disk to create.
• src_disk_id (int) – id of the source disk.
Returns struct – disk_create Operation
hosting.disk.delete(apikey, disk_id)
Delete a disk. ALL DATA WILL BE ERASED.Free the quota used by the disk size.The disk must not be attached to a VM.
Parameters
• apikey (string) – user identification key.
• disk_id (int) – unique disk identifier.
Returns struct – the disk_delete operation
62 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
hosting.disk.info(apikey, disk_id)Get information about a disk.
Parameters
• apikey (struct) – user identification key.
• disk_id (int) – disk unique identifier.
Returns struct – the disk information
hosting.disk.list(apikey[, filtering=nil])List the disks.
Available filters are:
•id
•datacenter_id
•name
•size
•state
•type
•vm_id.
Parameters
• apikey (string) – user identification key.
• filtering (struct) – optionnal parameter to filter and sort list result (see Filters).
Returns list of struct – list of disks
hosting.disk.list_kernels(apikey, datacenter_id)Get the list of available kernels for the given datacenter.
Parameters
• apikey (struct) – user identification key.
• datacenter_id (int) – id of the datacenter.
Returns struct – list of kernels
hosting.disk.list_options(apikey, kernel_version)List all available options for the given kernel version.
Parameters
• apikey (struct) – user identification key.
• kernel_version (string) – the version of the kernel.
Returns nil
hosting.disk.rollback_from(apikey, snapshot_id)
Rollback a disk to the last taken snapshot.
Parameters
• apikey (struct) – user identification key.
5.3. Hosting API Reference 63
Gandi API Client Manual Documentation, Release 2.0-beta
• snapshot_id (int) – snapshot identifier to rollback.
Returns struct – a disk_rollback_from Operation with the id of the new disk
hosting.disk.update(apikey, disk_id, disk_spec)
Update a disk with the given disk_spec.By now, you can’t shrink a disk.
If you update kernel or kernel_cmdline, you will have to restart the VM where the disk is attached.
If the size is modified the logged user must have enough free disk quota.
When updating name or size, if the disk is attached to a VM, this VM will be automatically rebooted.
Parameters
• apikey (struct) – user identification key.
• disk_id (int) – disk unique identifier.
• disk_spec (struct) – new attributes value.
Returns struct – a disk_update operation
Mappings
Disk information
Returned by hosting.disk.list() and hosting.disk.info()
name value nul-lable
description
id positive integer no unique identifiername string (regexp:
^[-_0-9a-z]{1,15}$)no name of the disk (unique for a user)
date_created datetime as string no date of creationdate_updated datetime as string no date of the last updatesize positive integer (by multiple of
1024)no size of the disk (unit in MB)
state being_created | created no state of the disk (is the disk currently being createdor totally created)
source positive integer yes id of the source disk (from which disk this disk hasbeen copied)
visibility all | private | alpha no define to whom the disk is visibletype data | backup |
snapshotno differentiate the properties of a disk
is_boot_disk boolean no true if the disk is attached at position 0 (the VM willboot on)
vms_id list of unique identifiers yes list of id of VMs to which the disk is attachedker-nel_version
string yes version of the kernel (ex: 2.6.18)
label string yes name of OS installed on the diskdatacen-ter_id
positive integer no where the disk is located
can_snapshot boolean no can a snapshot be created from this disk
This is added when using hosting.disk.info():
64 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
name value nullable descriptionkernel_cmdline string yes the associated command line
Disk Creation Mapping
Parameter of hosting.disk.create():
name manda-tory
value description
datacen-ter_id
manda-tory
positive integer where the resource will be located
name manda-tory
string (regexp:^[-_0-9a-z]{1,15}$)
name of the disk
size manda-tory
positive integer (by multiple of1024)
size of the disk (unit in MB)
type manda-tory
data | backup specify backup if you want a backup disk, dataotherwise
re-pulse_from
optional unique identifier or sequence ofunique identifier
ensure that the new disk will not be located on thesame filer as given disks
Disk kernel list
name value descriptionlinux list of strings list of available kernels for linux OSbsd list of strings list of available kernels for bsd OS
Example:
>>> api.disk.list_kernels(apikey, 1){’linux’: [’2.6.18’, ’2.6.27’, ’2.6.32’]}
Disk types
• data: default type used to store data. You can:
– attach it to a VM as a block device, then read and write data
– if attached at position 0 (vm.disk_attach()) , disk.is_boot_disk is true and the VM boots onthis disk
– if the attribute disk.can_snapshot is true, create an on-demand snapshot of the disk
• backup:
– on other filers than data disks
– slower than data disks
– support the same operations as data disks
• snapshot:
– represents the state of a disk at the time you made the snapshot of the disk
– cannot be attached on a VM. You have to create (disk.create_from()) or rollback(disk.rollback_from() and vm.disk_rollback()) a disk from the snapshot to access the data.
5.3. Hosting API Reference 65
Gandi API Client Manual Documentation, Release 2.0-beta
Disk command line options list
Mapping of available options for the command lineKeys are the options, and the value is a mapping describing the option.For example::
>>> api.disk.list_options(apikey, ’2.6.27’)>>> {’console’: {’choices’: [’xvc0’, ’hvc0’, ’tty1’], ’type’: ’list’},>>> ’loglevel’: {’default’: 4, ’type’: ’int’, ’validator’: ’^[0-8]$’},>>> ’nosep’: {’default’: True, ’hidden’: True, ’mandatory’: True, ’type’: ’bool’},>>> ’ro’: {’type’: ’bool’},>>> ’root’: {’choices’: [’/dev/xvda’, ’/dev/xvda1’, ’/dev/xvdb’],>>> ’default’: ’/dev/xvda1’,>>> ’mandatory’: True,>>> ’type’: ’list’},>>> ’selinux’: {’default’: 0, ’type’: ’int’, ’validator’: ’^(0|1)$’},>>> ’single’: {’type’: ’bool’}}
The mapping given for an option can have the following information:
name value descriptiontype string the type of the option (can be list | bool | int)default – the default value for this option (type is given by type)choices se-
quencepossible values for the option (only present when type is list)
hidden boolean used to prevent this option from being displayed in our frontend (usually used inconjunction with mandatory)
manda-tory
boolean boolean to know if this option is mandatory to have a valid command line (omitted meansFalse)
validator string regular expression to validate the parameter
Disk Copy attributes
Parameter of disk.create_from():
name manda-tory
value description
name manda-tory
string (regexp:^[-_0-9a-z]{1,15}$)
name of the disk
datacen-ter_id
optional positive integer where the resource will be located
re-pulse_from
optional unique identifer or sequence ofunique identifier
ensure that the new disk will not be located on thesame filer as given disks
type optional data | snapshot defines the type of disk to create
If the parameter datacenter_id is not provided, it will be copied from the source disk. In any case, the datacenter_idmust match source disk datacenter_id
The “kernel” parameter is inherited from the source disk.
66 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
Disk Update attributes
name manda-tory
value description
name optional string (regexp:^[-_0-9a-z]{1,15}$)
name of the disk
size optional positive integer (by multiple of 1024) size of the disk (unit in MB)kernel optional string (regexp: ...) change the kernel (ex: 2.6.18)cmd-line_options
optional mapping change the command line, given as amapping
cmdline optional string change the command line, given as astring
All attributes are optional, but you have to provide at least one parameter.
Setting a kernel will allow you to create VMs using this as a source disk (see disk.create_from() andvm.create())
5.3.5 Network Interface API Reference
hosting.iface
Network interfaces API Interface.A network interface that can be attached/detached to/from a VM.
hosting.iface.count(apikey[, filtering=nil])Count network interfaces that match the filter.
Available filters are:
•id
•vm_id
•state
•type.
Parameters
• apikey (string) – user identification.
• filtering (struct) – optional parameter to filter results (see Filters).
Returns int – number of network interfaces
hosting.iface.create(apikey, iface_spec)Create a network interface with the given information.
Parameters
• apikey (string) – user identification key.
• iface_spec (struct) – description of the network interface.
Returns struct – an iface_create operation
hosting.iface.delete(apikey, iface_id)Delete a network interface.
5.3. Hosting API Reference 67
Gandi API Client Manual Documentation, Release 2.0-beta
Parameters
• apikey (string) – user identification key.
• iface_id (int) – network interface to delete.
Returns struct – an iface_delete operation
hosting.iface.info(apikey, iface_id)Get information about a network interface.
Parameters
• apikey (string) – user identification key.
• iface_id (int) – network interface parameter.
Returns struct – the network interface information
hosting.iface.ip_attach(apikey, iface_id, ip_id)Attach an IP to a network interface.
Parameters
• apikey (string) – user identification key.
• iface_id (int) – network interface unique identifier.
• ip_id (int) – IP unique identifier.
Returns nil
hosting.iface.ip_detach(apikey, iface_id, ip_id)Detach an IP from a network interface.
Parameters
• apikey (string) – user identification key.
• iface_id (int) – network interface unique identifier.
• ip_id (int) – IP unique identifier.
Returns struct – an ip_detach operation
hosting.iface.list(apikey[, filtering=nil])List network interfaces that match the filter.
Available filters are:
•id
•vm_id
•state
•type.
Parameters
• apikey (string) – user identification key.
• filtering (struct) – optionnal parameter to filter list result (see Filters).
Returns list of struct – a list of dict describing the interfaces
hosting.iface.update(apikey, iface_id, iface_spec)Updates network interface information.
68 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
Parameters
• apikey (string) – user identification key.
• iface_id (int) – the network interface to update.
• iface_spec (struct) – expected network interface description.
Returns struct – an iface_update operation
Mappings
Iface attributes
name value descriptionid positive integer unique identifier of the network interfacedatacen-ter_id
positive integer where the resource is located (defined by contained IPs)
date_created datetime as string when the resource was createddate_updated datetime as string when the resource was last updatednum 0 .. ?? position of attachment to the VMstate free | used state of the resourcebandwidth positive integer (can be zero) amount of bandwidth allocated for this network interface
(unit in Kbps)type public | private is the interface public or private? (NOT WORKING)vm_id positive integer (empty string if not
attached)unique identifier of the VM where the network interface isattached
ips_id sequence of positive integer sequence of unique identifier of attached IPs
Iface Create mapping
name manda-tory
value description
datacen-ter_id
manda-tory
positive integer where the resource will be located
ip_version manda-tory
4 | 6 (integer) version of the IP that will be created
bandwidth optional positive integer (can be 0) (limitedby quota)
allocate given bandwidth directly at creation(unit in Kbps)
Iface Update mapping
name value descriptionbandwidth positive integer (can be 0) (limited by quota) change bandwidth for the network interface (unit in Kbps)
5.3.6 IP Address API Reference
hosting.ip
IP Address API Interface.
5.3. Hosting API Reference 69
Gandi API Client Manual Documentation, Release 2.0-beta
hosting.ip.count(apikey[, filtering=nil])Count IP Addresses that match the filter
Available filters are:
•id
•datacenter_id
•state
•reverse
•version
•ip.
Parameters
• apikey (string) – the user identification.
• filtering (struct) – optional parameter to filter results (see Filters).
Returns int – number of IPs matching the filter
hosting.ip.create(apikey, ip_spec)Create an IP Address with the given description.
First try to recycle an existant free IP for this hosting account inthe expected datacenter. If none is available, create an operation toallocate a new IP.Checks the quota to create a new IP only if can’t recycle an IP.
Parameters
• apikey (string) – the user identification.
• ip_spec (struct) – the description of the IP to create.
Returns struct – an ip_create Operation
hosting.ip.delete(apikey, ip_id)
Delete an IP Address.Actually, just detach the IP from the associated iface and let it as state ‘free’.The IP will be recycled for the next IP creation.
Parameters
• apikey (string) – the user identification.
• ip_id (int) – IP unique identifier.
Returns struct – ip_delete operation
hosting.ip.info(apikey, ip_id)Get information about an IP Address.
Parameters
70 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
• apikey (string) – the user identification.
• ip_id (int) – IP unique identifier.
Returns struct – the IP Address information
hosting.ip.list(apikey[, filtering=nil])List IP Addresses that match the filter
Available filters are:
•id
•datacenter_id
•state
•reverse
•version
•ip
•iface_id
•num.
Parameters
• apikey (string) – the user identification.
• filtering (struct) – optionnal parameter to filter list result (see Filters).
Returns struct – a list of IP descriptions
hosting.ip.update(apikey, ip_id, ip_spec)Update an IP Address with the given description.
Parameters
• apikey (string) – the user identification.
• ip_id (int) – the IP to update.
• ip_spec (struct) – the IP Address description.
Returns struct – the ip_update operation
5.3. Hosting API Reference 71
Gandi API Client Manual Documentation, Release 2.0-beta
Mappings
IP Information
name values descriptionid positive integer unique identifier of the IPdatacen-ter_id
positive integer where the resource is located
iface_id positive integer unique identifier of the networkinterface, if attached
date_created datetime as string when the resource was createddate_updateddatetime as string when the resource was last updatedip string (regexp: ) IP addressreverse string (regexp:
^(?:(?!-)[-a-zA-Z0-9]{1,63}(?<!-)(\.|$))+$)reverse
state being_created | created state of the resourceversion 4 | 6 (integer) version of the IP addressnum 0 .. 7 (integer) define the position of the IP on the
network interface
The num attribute represents the position of the IP on the network interface. The very first attached IP will be atposition 0. There is a maximun of 8 IP per network interface.
IP Create information
name manda-tory
values description
datacen-ter_id
manda-tory
positive integer where the resource willbe located
ip_version manda-tory
4 | 6 (integer) version of the IP address
reverse optional string (regexp:^(?:(?!-)[-a-zA-Z0-9]{1,63}(?<!-)(\.|$))+$)
reverse for the newlycreated IP
IP Update information
name values descriptionreverse string (regexp: ^(?:(?!-)[-a-zA-Z0-9]{1,63}(?<!-)(\.|$))+$) reverse for the IP
5.3.7 Virtual Machine API Reference
hosting.vm
Virtual Machine API Interface.
hosting.vm.count(apikey[, filtering=nil])Count virtual machine that match the filter.
Available filters are:
•id
•memory
72 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
•state
•cores
•hostname
•cores
•datacenter_id.
Parameters
• apikey (string) – user identification key.
• filtering (struct) – optional parameter to filter result (see Filters).
Returns int – number of VM matching the filter
hosting.vm.create(apikey, vm_spec)
Create a new virtual machine with the given information.Disk, iface, and vm MUST be in the same datacenter.
Parameters
• apikey (string) – user identification key.
• vm_spec (struct) – the VM to create.
Returns list of struct – a iface_create and a vm_create operation
hosting.vm.create_from(apikey, vm_spec, disk_spec, src_disk_id)
Creates a disk and a virtual machine.This is a convenient method to do the disk.create and vm.create in a single API call.
Parameters
• apikey (string) – user identification key.
• vm_spec (struct) – the VM to create.
• disk_spec (struct) – the Disk to create.
• src_disk_id (int) – the source disk.
Returns list of struct – a disk_create, iface_create and a vm_create operation
hosting.vm.delete(apikey, vm_id)
Deletes a VM.Deletes the disk attached in position 0, the disk used as system disk.Also deletes the first network interface.Detach all extra disks and network interfaces.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – the id of the VM.
5.3. Hosting API Reference 73
Gandi API Client Manual Documentation, Release 2.0-beta
Returns struct – the vm_delete operation
hosting.vm.disk_attach(apikey, vm_id, disk_id[, options=nil])
Attach a disk to a Virtual Machine.To access the disk data inside the VM, it MUST be attached to the VM.When options.position is 0, swaps position with current disk 0.A disk can only be attached to one VM.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – id of the VM.
• disk_id (int) – id of the disk to attach.
• options (struct) – optional options for the disk attachment.
Returns struct – a disk_attach operation
hosting.vm.disk_detach(apikey, vm_id, disk_id)
Detach a disk from a VM.If the disk position is 0, the VM MUST be halted to detach the disk.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – id of the VM.
• disk_id (int) – id of the disk to attach.
Returns struct – a disk_detach operation
hosting.vm.disk_rollback(apikey, snapshot_id)
Helper method to rollback a disk (instead of hosting.disk.rollback_from()).
Rollbacking a disk is done by creating a new disk using the given snapshot as source, the old disk is deletedafterwards. So, if the disk you try to rollback is attached to the VM, this method will create operations to stopthe VM, detach the old disk, create and attach the new one, and start the VM.
Parameters
• apikey (string) – user identification key.
• snapshot_id (int) – snapshot unique identifier.
Returns struct – list of operations
hosting.vm.iface_attach(apikey, vm_id, iface_id)
Attachs a network interface on the VM.No magic update is made on the interface bandwidth when attaching.You have to manually updates interface bandwidth as you desire.
74 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
Parameters
• apikey (string) – user identification key.
• vm_id (int) – VM unique identifier.
• iface_id (int) – network interface unique identifier.
Returns struct – iface_attach operation
hosting.vm.iface_detach(apikey, vm_id, iface_id)
Detachs a network interface from the VM.There is no restriction on detaching every interfaces.The VM will be unreachable if you choose to detach all interfaces.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – VM unique identifier.
• iface_id (int) – network interface unique identifier.
Returns struct – iface_detach operation
hosting.vm.info(apikey, vm_id)Get information about a virtual machine.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – the id of the VM.
Returns struct – The vm information
hosting.vm.list(apikey[, filtering=nil])Returns the virual machine that match the filter.
Available filters are:
•id
•memory
•state
•cores
•hostname
•cores
•datacenter_id.
Parameters
• apikey (string) – user identification key.
• filtering (struct) – optional parameter to filter the list (see Filters).
Returns struct – list of VM description
5.3. Hosting API Reference 75
Gandi API Client Manual Documentation, Release 2.0-beta
hosting.vm.reboot(apikey, vm_id)
Reboot a Virtual MachineA reboot message is sent to the VM. If it does not reboot properly after | 2 minutes, it is hard-reset (powercycled).
Parameters
• apikey (string) – user identification key.
• vm_id (int) – the id of the VM.
Returns struct – the vm_reboot operation
hosting.vm.start(apikey, vm_id)start a virtual machine.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – the id of the VM.
Returns struct – the vm_start operation
hosting.vm.stop(apikey, vm_id)
Stop a virtual machine.A stop message is sent to the VM. If it does not shutdown properly after two stop messages and 5 minutes, theVM is “power switched”.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – the id of the VM.
Returns struct – the vm_stop operation
hosting.vm.update(apikey, vm_id, update_spec)Updates a virtual machine with the given information.
Parameters
• apikey (string) – user identification key.
• vm_id (int) – the id of the VM.
• update_spec (struct) – description of the virtual machine.
Returns struct – the vm_update operation
Mappings
VM attributes
Returned by host.vm.info() and host.vm.list()
76 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
name values descriptionid positive integer unique identifierdatacenter_id positive integer where the resource is locatedhostname string name of the VMdescription string small description of the VMstate being_created | halted | running state of the VMmemory 256 | 320 | 384 | .. | 12288 (unit in MB) (by slice of 64) current amount of memoryvm_max_memory 2048 | 4096 | 6144 (unit in MB) maximum amount of memory the VM can handlecores 1 .. 6 number of coresflex_shares positive integer number of flex sharesdate_created datetime when the resource was createddate_updated datetime when the resource was last updatedconsole positive integer (0 or 1) is the rescue console active?ai_active positive integer (0 or 1) is the VM a GandiAI VM ?cores positive integer how many core the VM hasifaces_id list of positive integer list of attached network interfacesdisks_id list of positive integer list of attached disks
Note: the whole list of state is: paused | running | halted | locked | being_created | invalid |legally_locked | deleted
Other state that being_created | halted | running are extraordinary states, meaning that your VM is invalid.You will have to contact Gandi Support.
Virtual Machine Information
Parameter of host.vm.create()
name manda-tory
Values description
host-name
manda-tory
String (regexp: ) name of the VM (must be unique in your currentlycreated VMs)
memory manda-tory
256 | .. | 12288 (limitedby your quota)
(by slice of 64) amount of memory for the VM
shares optional 1 .. 24 number of shares for the VM (deprecated, kept forcompat)
cores optional 1 .. 6 (limited by your quota) number of cores for the VMband-width
optional 0 .. ? (limited by your quota) amount of bandwidth to assign for the automaticallycreated iface (unit in Kbps)
datacen-ter_id
manda-tory
positive integer where the resource will be located
sys_disk_id manda-tory
positive integer disk to use as the system disk (no copy is made, disk issimply attached).
ip_version manda-tory
4 | 6 (integer) version of IP you want to create
password manda-tory
string (regexp: ^[-~]{8,64}$)
password for root user (and created user, if login isgiven)
login optional string (regexp: ) the name of the unix account that will be created
Deprecated since version 2010/11/29: the attribute shares is deprecated. You can still provide it, but you will need tomodify your scripts to pass cores and bandwidth
Note: 2011/11/01 the attribute “sys_disk_id” must refer to a disk with a valid kernel (see disk.update() anddisk.create_from())
5.3. Hosting API Reference 77
Gandi API Client Manual Documentation, Release 2.0-beta
VM Creation
Parmeter of vm.create_from()
name manda-tory
values description
host-name
manda-tory
string (regexp: ) name of the VM (must be unique in your currentlycreated VMs)
memory manda-tory
256 | .. | 12288 (limitedby your quota)
(by slice of 64) amount of memory for the VM
shares optional 1 .. 24 number of shares for the VM (deprecated, kept forcompat)
cores optional 1 .. 6 (limited by your quota) number of cores for the VMband-width
optional 0 .. ? (limited by your quota) amount of bandwidth to assign for the automaticallycreated iface (unit in Kbps)
datacen-ter_id
manda-tory
positive integer where the resource will be located
ip_version manda-tory
4 | 6 (integer) version of IP you want to create
password manda-tory
string (regexp: ^[-~]{8,64}$)
password for root user (and created user, if login isgiven)
ai_active optional 0 | 1 is your VM will be a GandiAI ?login optional string (regexp: ) the name of the unix account that will be created
Deprecated since version 2010/11/29: the attribute shares is deprecated. You can still provide it, but you will need tomodify your scripts to pass cores and bandwidth
VM Update
name manda-tory
values description
vm_max_memoryoptional 2048 .. 12288 (by multiple of 64) maximum amount of memory the VMcan handle
cores optional 1 .. 6 (limited by quota) number of cores for the VMmemory optional 256 .. 12288 (by multiple of 64)
(limited by quota)amount of memory for the VM
console optional 0 | 1 enable or disable the rescue consolepassword optional string (regexp: ^[ -~]{8,64}$) update the password for the rescue
console
Every parameters are optional. You need to provide at least one parameter to update.
Disk attachment options
name mandatory values descriptionposition optional 0 position of the disk on the VMaccess optional read | read/write (default) how the disk will be mounted on the VM
All parameters are optional. The parameter options of disk.create() is optional. The access option defaultsto read/write. The position parameter can only take 0 as we only use it to swap disks in place.
78 Chapter 5. Gandi Hosting API
Gandi API Client Manual Documentation, Release 2.0-beta
5.4 Hosting Changelog
Changed in version 2011/09/19: add a hosting top level namespace.(eg: ip -> hosting.ip, vm -> hosting.vm,... )Changed in version 2010/10/25: Uses of XMLRPC extension to allow returning “nil”.Changed in version2010/10/25: iface.list() now returns ips_id instead of ips (see iface-return)Changed in version 2010/10/26:disk.update() now raises if trying to shrink the diskChanged in version 2010/10/26: vm.create()and vm.create_from(): the password parameter is now mandatory (vm-create-spec and vm-create-from-spec)Changed in version 2010/10/27: operation.info() now really returns a mapping, instead of a se-quenceChanged in version 2010/10/28: ip.list() accepts iface_id and num filterChanged in version 2010/10/28:ip.list() and ip.info() now returns the num attribute (see ip-return)Changed in version 2010/10/28: Theversion (see ip-return) attribute returned by ip.list() and ip.info() is now an integer, to stick with theip_version attribute which is an integerChanged in version 2010/11/26: The state (see ip-return) attribute changed:being_created or created instead of free or usedChanged in version 2010/11/29: shares is now depre-cated, and will be soon unavailable. You will have to manually manage cores and bandwidth instead of shares(see vm-return, vm-create-spec, vm-create-from-spec). shares will be totally removed at the end of the beta pe-riod.Changed in version 2010/11/29: Maximun amount of memory for a VM is now 12GB (see VM Update, vm-create-from-spec, vm-create-spec, vm-return)Changed in version 2010/12/06: Removed disk.get_options(), replacedby disk.list_kernels() and disk.list_options()Changed in version 2010/12/15: Added the ‘iso’attribute in datacenter.list() (see dc-return)Changed in version 2011/01/20: disk.list_kernels()now takes an additional datacenter_id parameterChanged in version 2011/01/27: Fixed a typo, the maximunnumber of allowed cores per VM is 6, not 8Changed in version 2011/02/16: The parameter datacenter_idis now optional in disk.create_from() (see disk-create-from)Changed in version 2011/05/04: Documentsdisk.rollback_from() and vm.disk_rollback()
5.4. Hosting Changelog 79
CHAPTER
SIX
GANDI OPERATION API
6.1 Operation API Reference
6.1.1 operation
operation.cancel(apikey, operation)Set the step of an operation to CANCEL.
Parameters
• apikey (string) – The user identification.
• operation (int) – The ID of the operation.
Returns boolean – Boolean
operation.count(apikey[, opts=nil])Count operations visible by this account.
Parameters
• apikey (string) – The user identification.
• opts (struct) – Options to filter the result (see Filters).
Returns int – The number of operations found.
operation.info(apikey, operation)Return some attributes of a operation visible by this account.
Parameters
• apikey (string) – The user identification.
• operation (int) – The ID of the operation.
Returns struct – Information about the operation
operation.list(apikey[, opts=nil])List operations done by this account.
Parameters
• apikey (string) – The user identification.
• opts (struct) – Options to filter the result (see Filters).
Returns struct – list of operations
81
CHAPTER
SEVEN
GANDI CATALOG API
7.1 Catalog API
7.1.1 Introduction
The Gandi catalog API provides a set of remote requests to get all gandi products with their associated catalog.
7.1.2 Connect to the API server
The Gandi Catalog API is provided through a set of XML-RPC calls. The first step is to connect to the API.
In Python, use the xmlrpclib module from the standard library:
>>> import xmlrpclib>>> api = xmlrpclib.ServerProxy(’https://rpc.gandi.net/xmlrpc/’)>>>>>> # assign your API key to a variable:>>> apikey = ’my 24-character API key’>>>>>> # Now you can call API methods.>>> # You must authenticate yourself by passing the API key as the first method’s argument>>> domains = api.domain.list(apikey)
Note: In Python 3 xmlrpclib has been renamed xmlrpc.client
In PHP 5, with the XML_RPC2 package from pear:
<?php// Library installed from PEARrequire_once ’XML/RPC2/Client.php’;
// The first step is to connect to the API$domain_api = XML_RPC2_Client::create(
’https://rpc.gandi.net/xmlrpc/’,array( ’prefix’ => ’domain.’ )
);
// assign your API key to a variable$apikey = ’my 24-character API key’;
// Now you can call API method
83
Gandi API Client Manual Documentation, Release 2.0-beta
// You must authenticate yourself by passing the API key as the first method’s argument$result = $domain_api->list($apikey);
// dump the resultprint_r($result);?>
Note: XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have toinstanciante a client by namespace
With NodeJS, use the xmlrpc package from npm:
> var xmlrpc = require(’xmlrpc’)> var api = xmlrpc.createSecureClient({... host: ’rpc.gandi.net’,... port: 443,... path: ’/xmlrpc/’... })>> //Assign your API key to a variable> var apikey = ’my 24-character API key’>> // Now you can call API methods.> // You must authenticate yourself by passing the API key as the first method’s argument> api.methodCall(’domain.list’, [apikey], function (error, value) {... console.dir(value)... })
use XML::RPC;
my $api = XML::RPC->new(’https://rpc.gandi.net/xmlrpc/’);
# assign your API key to a variable:my $apikey = ’my 24-character API key’;
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentmy $domains = $api->call( ’domain.list’, $apikey );
require ’xmlrpc/client’
server = XMLRPC::Client.new2(’https://rpc.gandi.net/xmlrpc/’)
# assign your API key to a variable:apikey = ’my 24-character API key’
# Now you can call API methods.# You must authenticate yourself by passing the API key as the first method’s argumentdomains = server.call("domain.list", apikey)
Note: Store the API key in a safe place.
84 Chapter 7. Gandi Catalog API
Gandi API Client Manual Documentation, Release 2.0-beta
Get domain
>>> # retrieve all price for domains>>> api.catalog.list(apikey, {’product’:{’type’: ’domains’}})
Get domain for specific tlds
>>> # retrieve one tld>>> api.catalog.list(apikey, {’product’:{’type’: ’domains’, ’description’: ’.fr’}})>>> # retrieve one tld>>> api.catalog.list(apikey, {’product’:{’type’: ’domains’,... ’description’: [’.net’, ’.com’, ’.org’]}})
Get domain for specific tlds for a create operation
>>> # for all duration>>> api.catalog.list(apikey, {’product’:{’type’: ’domains’,... ’description’: [’.net’, ’.org’]},... ’action’: {’name’: ’create’}})>>> # for a specific duration>>> api.catalog.list(apikey, {’product’:{’type’: ’domains’,... ’description’: [’.net’, ’.org’]},... ’action’: {’name’: ’create’, ’duraction’: 5}})
Get domain for specific tlds for a transfer or a renew operation
>>> api.catalog.list(apikey, {’product’:{’type’: ’domains’,... ’description’: [’.net’, ’.org’]},... ’action’: {’name’: [’transfer’,’renew’]}})
Get Hosting resource
>>> api.catalog.list(apikey, {’product’:{’type’: ’hosting’}})
Get T-Shirts
>>> # retrieve all price for tshirts>>> api.catalog.list(apikey, {’product’:{’type’: ’tshirts’}})
Get Paas
>>> # retrieve all price for paas>>> api.catalog.list(apikey, {’product’:{’type’: ’pass’}})>>> # retrieve phpmysql pricing without obligation>>> api.catalog.list(apikey,{’product’: {’type’:’paas’,... ’description’: [’phpmysql_s’,... ’phpmysql_m’,... ’phpmysql_l’]}}))
7.1. Catalog API 85
Gandi API Client Manual Documentation, Release 2.0-beta
7.2 Catalog API Reference
7.2.1 catalog
catalog.list(apikey[, spec=nil, currency=’EUR’, grid=’A’])List available products that match the filter.
Parameters
• apikey (string) – user identification key.
• spec (struct) – Options to filter the result.
• currency (string) – an ISO currency (‘EUR’, ‘GBP’ or ‘USD’).
• grid (string) – a grid name.
Returns list of struct – list of products
7.2.2 Mappings
catalog request list
Parameter of catalog.info()
This is a list of _productsearchoptions-type. You should use this method with alls parameters and search for more thanone result in one call. Otherwise you should use a catalog.list() method.
Warning:The catalog.info() method could be slow,You should try to use catalog.list() rather,leave yourself a filtering result if your request is really specific.
Parameter of catalog.list()
catalog request
name type mandatory descriptionproduct product-type mandatory the requested product specaction action-type optional the associated action for the entrie
product
name type mandatory descriptiontype string or list of string mandatory the requested product’s category(ies)description string or list of string optional the requested product’s name(s)
action
name type mandatory descriptionname string or list of string optional the action’s applied for the productduration int optional the contract duration
86 Chapter 7. Gandi Catalog API
Gandi API Client Manual Documentation, Release 2.0-beta
Possible actions name :
activate -add -change_owner -create create a domaindeactivate -delete -release release an hosting resourceremove -renew renew a domainrestore -transfer transfer from the registrar of the domaintransfer_reseller transfer the domain resellerupdate -
Returned by catalog.info() or catalog.list():
catalog entry
name type descriptionaction action-type the associated action for the entrieproduct product-type the associated product for the entrieunit_price list of unit price list of price for this product associated with this action
action
name type descriptionname string the name of the action
product
name type descriptiontype string the category of the productdescription string the name of the product
Possible product type :
domains domain namehosting hosting resourcetshirts t-shirtsgandimail gandimailsites sitemakercertificates SSL certificatespaas paas
7.2. Catalog API Reference 87
Gandi API Client Manual Documentation, Release 2.0-beta
unit price
name type descriptioncurrency string the price’s currencyprice double the contracted price, charge not includedgrid string the fee scheduleduration_unit string the duration (y: year, m: month)min_duration int the minimum contract durationmax_duration int the maximum contract durationspecial_op boolean special offer
Download this documentation as PDF.
88 Chapter 7. Gandi Catalog API
INDEX
Aavailable() (domain method), 24
Ccan_associate() (contact method), 40can_associate_domain() (contact method), 40cancel() (operation method), 81count() (domain method), 24count() (domain.host method), 26count() (hosting.disk method), 61count() (hosting.iface method), 67count() (hosting.ip method), 69count() (hosting.vm method), 72count() (namespace.obj method), 6count() (operation method), 81create() (contact method), 40create() (domain method), 24create() (domain.host method), 26create() (hosting.disk method), 62create() (hosting.iface method), 67create() (hosting.ip method), 70create() (hosting.vm method), 73create() (namespace.obj method), 6create_from() (hosting.disk method), 62create_from() (hosting.vm method), 73
Ddelete() (domain.host method), 27delete() (hosting.disk method), 62delete() (hosting.iface method), 67delete() (hosting.ip method), 70delete() (hosting.vm method), 73delete() (namespace.obj method), 6disk_attach() (hosting.vm method), 74disk_detach() (hosting.vm method), 74disk_rollback() (hosting.vm method), 74
Eerror codes, 50
Iiface_attach() (hosting.vm method), 74
iface_detach() (hosting.vm method), 75info() (contact method), 40info() (domain method), 25info() (domain.host method), 27info() (hosting.disk method), 63info() (hosting.iface method), 68info() (hosting.image method), 61info() (hosting.ip method), 70info() (hosting.vm method), 75info() (namespace.obj method), 6info() (operation method), 81ip_attach() (hosting.iface method), 68ip_detach() (hosting.iface method), 68
Llist() (catalog method), 86list() (contact method), 40list() (domain method), 25list() (domain.host method), 27list() (domain.tld method), 28list() (hosting.datacenter method), 60list() (hosting.disk method), 63list() (hosting.iface method), 68list() (hosting.image method), 61list() (hosting.ip method), 71list() (hosting.vm method), 75list() (namespace.obj method), 6list() (operation method), 81list_kernels() (hosting.disk method), 63list_options() (hosting.disk method), 63lock() (domain.status method), 26
Nnamespace.obj (built-in class), 6
Pproceed() (domain.transferin method), 28
Rreboot() (hosting.vm method), 75region() (domain.tld method), 28
91
Gandi API Client Manual Documentation, Release 2.0-beta
registry status, 36renew() (domain method), 25RFC
RFC 3731#section-2.3, 26RFC 5322#section-3.4.1, 33
rollback_from() (hosting.disk method), 63
Sset() (domain.contacts method), 26set() (domain.nameservers method), 28start() (hosting.vm method), 76stop() (hosting.vm method), 76
Uunlock() (domain.status method), 26update() (contact method), 40update() (domain.host method), 27update() (hosting.disk method), 64update() (hosting.iface method), 68update() (hosting.ip method), 71update() (hosting.vm method), 76update() (namespace.obj method), 6
92 Index