The Gandi Notification API provides a set of remote requests to manage your notifications.
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)
<?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);
?>
> 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.
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'}]
To count how many notifications are avalaible at a given time, just call the notification.count() method:
>>> api.notification.count(apikey)
23
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
Here are some samples of notifications content for SNS channels.
{'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'}
{'platform': 'production',
'domain': 'pizzza.xyz',
'source_notification': 'domain.transfer_out_done_reselle'}