Contact API

Introduction

The Gandi Contact API provides a set of remote requests to manage your contacts.

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.

>>> import xmlrpc.client
>>> api = xmlrpc.client.ServerProxy('https://rpc.gandi.net/xmlrpc/')
>>>
>>> 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
>>> version = api.version.info(apikey)

Note

In Python, use the xmlrpcclient module from the standard library.

<?php
// Library installed from PEAR
require_once 'XML/RPC2/Client.php';

// The first step is to connect to the API
$version_api = XML_RPC2_Client::create(
    'https://rpc.gandi.net/xmlrpc/',
    array( 'prefix' => 'version.', 'sslverify' => True )
);

// Warning !
// PEAR::XML_RPC2 checks the SSL certificate with Curl
// Curl has its own CA bundle so you may :
// * disable the 'sslverify' option: leads to security issue
// * enable the 'sslverify' option (default) and add the Gandi
// SSL certificate to the Curl bundle: best choice for security
// See: https://curl.haxx.se/docs/sslcerts.html

$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 = $version_api->info($apikey);

// Warning !
// PEAR::XML_RPC2 has known bugs on methods calls
// See https://pear.php.net/bugs/bug.php?id=13963
// You may use this call instead of the above one :
// $result = $version_api->__call("info", $apikey);

// dump the result
print_r($result);
?>

Note

In PHP 5, use the XML_RPC2 package from pear.

XML_RPC2 works with ‘prefix’ in order to bind to namespace. The ‘prefix’ isn’t editable, so you have to instanciante a client by namespace.

> var xmlrpc = require('xmlrpc')
> var api = xmlrpc.createSecureClient({
...  host: 'rpc.gandi.net',
...  port: 443,
...  path: '/xmlrpc/'
... })
>
> 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('version.info', [apikey], function (error, value) {
...  console.dir(value)
... })

Note

With NodeJS, use the npm xmlrpc package.

use XML::RPC;

my $api = XML::RPC->new('https://rpc.gandi.net/xmlrpc/');

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 argument
my $version = $api->call( 'version.info', $apikey );

Note

With perl, use the cpan xml::rpc package.

require 'xmlrpc/client'

server = XMLRPC::Client.new2('https://rpc.gandi.net/xmlrpc/')

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
version = server.call("version.info", apikey)

Note

With ruby, use the xmlrpc/client module from the standard library. Ruby does not support gzip by default, the ZlibParserDecorator is used to enabled with Ruby >1.9.

For older ruby version, neither set the http_header_extra nor the parser.

Note

To avoid RuntimeError with ruby >= 1.9, add:

XMLRPC::Config.module_eval {
    remove_const(:ENABLE_NIL_PARSER)
    const_set(:ENABLE_NIL_PARSER, true)
}

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <xmlrpc.h>
#include <xmlrpc_client.h>

#define CLIENT_NAME             "Documentation Client"
#define CLIENT_VERSION          "0.1"
#define CLIENT_USERAGENT        CLIENT_NAME "/" CLIENT_VERSION

#define SERVER_URL              "https://rpc.gandi.net/xmlrpc/"

int     client_connect(xmlrpc_env *);
void    client_check_fault(xmlrpc_env *);

int
main(int argc, char **argv)
{
        xmlrpc_env      env;
        xmlrpc_value    *apikey, *rv;

        client_connect(&env);

        apikey = xmlrpc_build_value(&env, "(s)", "my 24-character API key");
        rv = xmlrpc_client_call_params(&env, SERVER_URL, "version.info", apikey);
        client_check_fault(&env);

        xmlrpc_DECREF(rv);
        xmlrpc_DECREF(apikey);

        xmlrpc_env_clean(&env);
        xmlrpc_client_cleanup();

        return (0);
}

int
client_connect(xmlrpc_env *env)
{
        struct xmlrpc_clientparms clientp;
        struct xmlrpc_curl_xportparms curlp;

        curlp.network_interface = NULL;         /* use curl's default */
        curlp.ssl_verifypeer = 1;               /* Gandi API CA must be present */
        curlp.ssl_verifyhost = 2;
        curlp.user_agent = CLIENT_USERAGENT;    /* XML-RPC requirement */

        clientp.transport = "curl";
        clientp.transportparmsP = &curlp;
        clientp.transportparm_size = XMLRPC_CXPSIZE(user_agent);

        xmlrpc_env_init(env);
        xmlrpc_client_init2(env, XMLRPC_CLIENT_NO_FLAGS, CLIENT_NAME,
            CLIENT_VERSION, &clientp, XMLRPC_CPSIZE(transportparm_size));
        client_check_fault(env);

        return (1);
}

void
client_check_fault(xmlrpc_env *env)
{
        if (env->fault_occurred) {
                fprintf(stderr, "XML-RPC Fault: %s (%d)\n", env->fault_string,
                    env->fault_code);
                exit(1);
        }
}

Note

With C, use the xmlrpc-c library.

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 about 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 the contact(s).

Create a contact

To create a contact use the contact.create() method.

It requires an Gandi API Key and a dictionnary of contact information such as: * given and family names * email * postal address * phone * type of account * password

Note

type of account takes the following values 0 for a private customer 1 for a company 2 for an association 3 for a public body

>>> contact_spec = {
...   'given': 'First Name',
...   'family': 'Last Name',
...   'email': 'example@example.com',
...   '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)

Rights Delegation and AutoFoas

Reseller Contact may create Rights Delegations in order to avoid customer validation of Forms of Approval (such as those sent prior to a Change of Ownership or a Domain Transfer).

Obtaining a list of what Rights Delegations are associated to a Reseller Account is possible with the contact.autofoa.list() method

>>> api.contact.autofoa.list(apikey)

In order to create a Right Delegation - which we like to call an AutoFoa - a Reseller Contact can use the contact.autofoa.create() method:

>>> new_autofoa = api.contact.autofoa.create(apikey, {'email': 'address@customer.email'})

In order to validate the AutoFoa we will send an email containing a confirmation link to the address on which the right delegation is set-up (‘address@customer.email’ in this case).

The Reseller Contact can also call up the contact.autofoa.validate() method provided the Reseller Contact sends the authentifaction code contained in the confirmation email.

>>> api.contact.autofoa.validate(apikey, new_autofoa['id'], 'my-authentication-code')

If the Right Delegation is no longuer needed it can be deleted by simply calling up the contact.autofoa.delete() method with an AutoFoa id

>>> api.contact.autofoa.delete(apikey, new_autofoa['id'])