gandi api client manual documentation - etablis, … api client manual documentation, release...

Gandi API Client ManualDocumentation

Release 2.0-beta

Gandi Tech Team

January 09, 2012

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


# 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


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

http://www.xmlrpc.com/spec


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


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


8 Chapter 2. Introduction

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:








);


// Now you can call API method

9


// You must authenticate yourself by passing the API key as the first method’s argument$result = $domain_api->list($apikey);





use XML::RPC;







# 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: 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


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


... }

... }> 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’,



’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


’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);


http://pear.php.net/bugs/bug.php?id=13963


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


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



([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


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 :



• 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


<?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:



>>> 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


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’,



’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


$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


• 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


• fqdn (string) – The name of the domain to create.



• params (struct) – description of the domain.

Returns struct – the domain_create operation dict

domain.info(apikey, fqdn)get domain information.

Parameters


• 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


• 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


• 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


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


• 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


• 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


• 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


http://tools.ietf.org/html/rfc3731.html#section-2.3



• 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


• 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


• 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


• 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


• hostname (string) – The hostname to update.

• ips (array) – list of IPs to set.

Returns struct – The update operation



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


• fqdn (string) – The fqdn of the domain to alter.

• nameservers (array) – list of nameservers.



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


http://en.wikipedia.org/wiki/Fully_qualified_domain_name

http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes


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



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()



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



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


http://tools.ietf.org/html/rfc5322.html#section-3.4.1


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 -



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


>>> 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


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.








);



37







use XML::RPC;









38 Chapter 4. Gandi Contact API


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


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


• 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


• 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


• 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


• 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



contact.update(apikey, handle, contact)Check the same way as check and then update.

Parameters


• 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


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():



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


• 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

• email

• 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:



>>> 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’)]



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’,


},... ]

*/?>

4.3. Contact API FAQ 45


> 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 ...},... ]


}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



<?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’



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



$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’,


},... ]

*/



?>

> 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


}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’

}

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



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.


The Gandi Hosting API is provided through a set of XML-RPC calls.








);


53


// 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);





use XML::RPC;









54 Chapter 5. Gandi Hosting API


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


’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:



>>> 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


>>> 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:



>>> 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


• 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


• 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



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.


•id

•datacenter_id

5.3. Hosting API Reference 61


•name

•size

•state

•type

•vm_id.

Parameters


• 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


• 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


• 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


• disk_id (int) – unique disk identifier.

Returns struct – the disk_delete operation



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.


•id

•datacenter_id

•name

•size

•state

•type

•vm_id.

Parameters


• 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


• 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


• 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




• 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


• 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():



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.



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.



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.


•id

•vm_id

•state

•type.

Parameters

• apikey (string) – user identification.


Returns int – number of network interfaces

hosting.iface.create(apikey, iface_spec)Create a network interface with the given information.

Parameters


• iface_spec (struct) – description of the network interface.

Returns struct – an iface_create operation

hosting.iface.delete(apikey, iface_id)Delete a network interface.



Parameters


• 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


• 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


• 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




Returns struct – an ip_detach operation

hosting.iface.list(apikey[, filtering=nil])List network interfaces that match the filter.


•id

•vm_id

•state

•type.

Parameters


• 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.



Parameters


• 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


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.



hosting.ip.count(apikey[, filtering=nil])Count IP Addresses that match the filter


•id

•datacenter_id

•state

•reverse

•version

•ip.

Parameters



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


• 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



Returns struct – ip_delete operation

hosting.ip.info(apikey, ip_id)Get information about an IP Address.

Parameters





Returns struct – the IP Address information

hosting.ip.list(apikey[, filtering=nil])List IP Addresses that match the filter


•id

•datacenter_id

•state

•reverse

•version

•ip

•iface_id

•num.

Parameters


• 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


• ip_id (int) – the IP to update.

• ip_spec (struct) – the IP Address description.

Returns struct – the ip_update operation



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


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.


•id

•memory



•state

•cores

•hostname

•cores

•datacenter_id.

Parameters


• 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


• 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


• 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


• vm_id (int) – the id of the VM.



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


• 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


• 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


• 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.



Parameters


• vm_id (int) – VM 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


• vm_id (int) – VM unique identifier.


Returns struct – iface_detach operation

hosting.vm.info(apikey, vm_id)Get information about a virtual machine.

Parameters



Returns struct – The vm information

hosting.vm.list(apikey[, filtering=nil])Returns the virual machine that match the filter.


•id

•memory

•state

•cores

•hostname

•cores

•datacenter_id.

Parameters


• filtering (struct) – optional parameter to filter the list (see Filters).

Returns struct – list of VM description



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



Returns struct – the vm_reboot operation

hosting.vm.start(apikey, vm_id)start a virtual machine.

Parameters



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



Returns struct – the vm_stop operation

hosting.vm.update(apikey, vm_id, update_spec)Updates a virtual machine with the given information.

Parameters



• 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()



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


sys_disk_id manda-tory

positive integer disk to use as the system disk (no copy is made, disk issimply attached).


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())



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



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.



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


• operation (int) – The ID of the operation.

Returns boolean – Boolean

operation.count(apikey[, opts=nil])Count operations visible by this account.

Parameters



Returns int – The number of operations found.

operation.info(apikey, operation)Return some attributes of a operation visible by this account.

Parameters


• 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



Returns struct – list of operations

81


82 Chapter 6. Gandi Operation API

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.


The Gandi Catalog API is provided through a set of XML-RPC calls. The first step is to connect to the API.








);



83







use XML::RPC;









84 Chapter 7. Gandi Catalog API


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


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


• 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



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


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.


CHAPTER

EIGHT

INDICES AND TABLES

• genindex

• search

89


90 Chapter 8. Indices and tables

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


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