Gandi

Table Of Contents

Previous topic

Gandi Notification API

Next topic

Notification API Reference

Notification API

Introduction

The Gandi Notification API provides a set of remote requests to manage your notifications.

Connect to the API server

The Gandi Notification API is provided through a set of XML-RPC calls:

>>> import xmlrpclib
>>> api = xmlrpclib.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 xmlrpclib module from the standard library.

In Python 3 xmlrpclib has been renamed xmlrpc.client.

<?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: http://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 http://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'

class ZlibParserDecorator
  def initialize(parser)
    @parser = parser
  end
  def parseMethodResponse(responseText)
    @parser.parseMethodResponse(Zlib::GzipReader.new(StringIO.new(responseText)).read)
  end
  def parseMethodCall(*args)
    @parser.parseMethodCall(*args)
  end
end


server = XMLRPC::Client.new2('https://rpc.gandi.net/xmlrpc/')
server.http_header_extra = { "Accept-Encoding" => "gzip" }
server.set_parser ZlibParserDecorator.new(server.send(:parser))

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.

Note

the Notification API does not use the standard HTTP authentication scheme. It uses a custom authentication mechanism based on the API key.

Notification Management

Explaining notifications

  • domain.delete_foa: This notification is sent when the FOA confirmation for a domain deletion is sent to the domain owner.
  • domain.delete_foa_reselle: This notification is sent when the FOA confirmation for a domain deletion is sent to the domain owner on behalf of the reseller.
  • domain.delete_done_reseller: This notification is sent to the reseller when a domain has been deleted from the registry.
  • domain.transfer_out: This notification is sent when GANDI has been notified of a registrar transfer request, to alert the domain owner that it will be effective in 5 days.
  • domain.transfer_out_reselle: This notification is sent when GANDI has been notified of a registrar transfer request, to alert the reseller that he will be unable to manage the domain from the GANDI account in 5 days.
  • domain.transfer_out_done_reselle: This notification is sent when the domain has been transfered to another registrar and is no longer managed by GANDI.
  • domain.reachability_reseller: This notification is sent to the reseller when a contact reachability status changes: pending, done, failed.
  • domain.contact_validation: This notification is sent to the domain owner or the reseller, when a contact validation data is required, as it is done for .uk.
  • iaas.create: This notification is sent after every server creation.
  • iaas.update: This notification is sent following each server modification.
  • paas.create: This notification is sent when a Simple Hosting instance is created.
  • site.create: This notification is sent when a website is created.
  • ssl.backend: These notifications will be sent during various certificate purchasing processes.
  • domain.creation: Not yet available.
  • domain.renewal_reminder: Not yet available.
  • domain.grouped_renewal_reminder: Not yet available.
  • domain.renewal: Not yet available.
  • domain.automatic_renewal: Not yet available.
  • domain.transfer: Not yet available.
  • domain.restore: Not yet available.
  • domain.change_owner: Not yet available.
  • domain.update: Not yet available.
  • contact.update: Not yet available.
  • contact.password_update: Not yet available.
  • billing.new_invoice: Not yet available.
  • billing.credit_alert: Not yet available.
  • iaas.credit_alert: Not yet available.
  • paas.renewal_reminder: Not yet available.
  • paas.renewal: Not yet available.
  • site.renewal_reminder: Not yet available.
  • site.renewal: Not yet available.
  • ssl.renewal_reminder: Not yet available.

List availables notifications

To list the available notifications and their associated channels, just call the method notification.list():

>>> api.notification.list(apikey)
[{'active': True,
  'channels': [{'name': 'irc', 'status': 'inactive'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'inactive'}],
  'name': 'billing.credit_alert'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'}],
  'name': 'billing.new_invoice'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'contact.password_update'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'contact.update'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.automatic_renewal'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.change_owner'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.creation'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'}],
  'name': 'domain.delete_done_reseller'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'}],
  'name': 'domain.delete_foa'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'}],
  'name': 'domain.delete_foa_reselle'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.grouped_renewal_reminder'},
 {'active': True,
  'channels': [{'name': 'sns', 'status': 'active'}],
  'name': 'domain.reachability_reseller'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.renewal'},
 {'active': False,
  'channels': [{'name': 'irc', 'status': 'inactive'},
               {'name': 'smtp', 'status': 'inactive'},
               {'name': 'xmpp', 'status': 'inactive'}],
  'name': 'domain.renewal_reminder'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.restore'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.transfer'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'inactive'}],
  'name': 'domain.transfer_out'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'inactive'}],
  'name': 'domain.transfer_out_reselle'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'domain.update'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'sns', 'status': 'active'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'iaas.create'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'inactive'},
               {'name': 'sms', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'inactive'}],
  'name': 'iaas.credit_alert'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'inactive'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'iaas.update'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'paas.create'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'paas.renewal'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'paas.renewal_reminder'},
 {'active': True,
  'channels': [{'name': 'irc', 'status': 'active'},
               {'name': 'smtp', 'status': 'active'},
               {'name': 'xmpp', 'status': 'active'}],
  'name': 'site.create'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'site.renewal'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'site.renewal_reminder'},
 {'active': True,
  'channels': [{'name': 'smtp', 'status': 'active'}],
  'name': 'ssl.backend'},
 {'active': False,
  'channels': [{'name': 'smtp', 'status': 'inactive'}],
  'name': 'ssl.renewal_reminder'}]

Count availables notifications

To count how many notifications are avalaible at a given time, just call the notification.count() method:

>>> api.notification.count(apikey)
23

Test your notification subscriptions

If you want to test your notifications setup, you may execute the notification.test() method:

>>> api.notification.test(apikey, 'paas.create')
True

You should then receive on all subscribed addresses a message saying

Hello, this is a Gandi Notification test message for notification paas.create

Notification content samples

Here are some samples of notifications content for SNS channels.

  • domain.reachability_reseller: This notification is sent to the reseller when a contact reachability status changes: pending, done, failed.
{'status': 'pending',
 'handle': 'XXXX1234-GANDI',
 'platform': 'production',
 'date_end': '2016-01-01 08:36:32',
 'date': '2015-12-17 08:39:06',
 'source_notification': 'domain.reachability_reseller',
 'domains': "['pizzza.xyz']",
 'date_created': '2015-12-17 08:35:20'}

{'status': 'done',
 'handle': 'XXXX1234-GANDI',
 'platform': 'production',
 'date_end': '2015-12-17 08:37:20',
 'date': '2015-12-17 10:48:27',
 'source_notification': 'domain.reachability_reseller',
 'domains': u"['pizzza.xyz']",
 'date_created': '2015-12-17 08:35:20'}

{'status': 'failed',
 'handle': 'XXXX1234-GANDI',
 'platform': 'production',
 'date_end': '2015-12-17 10:55:59',
 'date': '2015-12-17 10:59:06',
 'source_notification': 'domain.reachability_reseller',
 'domains': u"['pizzza.xyz']",
 'date_created': '2015-12-17 10:53:59'}
  • domain.transfer_out_done_reselle: This notification is sent when the domain has been transfered to another registrar and is no longer managed by GANDI.
{'platform': 'production',
 'domain': 'pizzza.xyz',
 'source_notification': 'domain.transfer_out_done_reselle'}