The Gandi PaaS API provides a set of remote requests to manage your PaaS instances.
The Gandi PaaS 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'
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.
#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 PaaS API does not use HTTP authentication scheme. It uses a custom authentication mechanism based on the API key.
To list the instances you own, just call the paas.list() method:
>>> api.paas.list(apikey)
[{ 'catalog_name': 'phpmysql_m',
'data_disk_additional_size': 0,
'datacenter_id': 1,
'date_end': <DateTime '20111014T14:36:30' at 7f96c47a0368>,
'date_end_commitment': None,
'date_start': <DateTime '20110914T14:36:30' at 7f96c47a03b0>,
'id': 1,
'name': 'Mon PaaS',
'need_upgrade': True,
'servers': [{'id': 1}],
'size': 'm',
'state': 'running',
'type': 'phpmysql'
}]
>>> api.paas.list(apikey, {'size':'s'})
[]
To count the PaaS instances you own, just call the paas.count() method:
>>> api.paas.count(apikey)
1
>>> api.paas.count(apikey, {'size':'s'})
0
Get info on an instance with method paas.info() method:
>>> api.paas.info(apikey, 1)
{
'autorenew': None,
'catalog_name': 'phpmysql_m',
'data_disk_additional_size': 0,
'datacenter': {'country': 'France', 'id': 1, 'iso': 'FR', 'name': 'eqx pa2'},
'date_end': <DateTime '20111014T14:36:30' at 7f96c47a0440>,
'date_start': <DateTime '20110914T14:36:30' at 7f96c47a0488>,
'ftp_server': '10.0.0.10',
'id': 1,
'name': 'Mon PaaS',
'owner': {'handle': 'XXX-GANDI', 'id': 1},
'servers': [{
'graph_urls': {'vcpu': ['http://console.gandi.net/?key=[...]'],
'vdi': ['http://console.gandi.net/?key=[...]'],
'vif': ['http://console.gandi.net/?key=[...]']},
'id': 1,
'uuid':1}],
'size': 'm',
'state': 'running',
'type': 'phpmysql',
'user': 2316,
'vhosts': [{
'date_creation': <DateTime '20110914T14:36:30' at 7f96c47a03f8>,
'id': 1,
'name': 'vhost.test.fr',
'state': 'running'
}
]}
To create a PaaS instance, use the paas.create() method by specifying a name, a size (one of s, m, l, xl, xxl), a type (phpmysql), a list of vhosts, a duration, and a password. You can also specify an optional disk size via the quantity attribute:
>>> paas_spec = {
'name': 'My PaaS',
'size': 'm',
'type': 'phpmysql',
'datacenter_id': 1,
'vhosts': ['vhost.test.fr'],
'quantity': 0,
'duration': '3m',
'password': 'xxxxxxxxxx'}
>>> ops = api.paas.create(apikey, paas_spec)
>>> len(ops)
3
>>> ops[0]['type']
'paas_vm_create'
>>> ops[1]['type']
'paas_disk_create'
>>> ops[2]['type']
'rproxy_create'
This will create an instance called “Mon Paas” of type “phpmysql”, size “m”. see https://www.gandi.net/hebergement/simple/puissance?lang=en for a full description of the different sizes), with the default 10 GB of disk, for 3 Months and one attached host (“vhost.test.fr”).
To update an instance, use the paas.update() method. You can specify a size, a quantity (of additional disk size in Go) and a password:
>>> op = api.paas.update(apikey, paas_id, {'size':'xl'})
>>> ops[0]['type']
'paas_vm_update'
To delete an instance, use the paas.delete() method:
>>> op = api.paas.delete(apikey, paas_id)
>>> op['type']
'paas_delete'
If you are not using the Gandi DNS or you did not registred your domain at Gandi, you can also run a PaaS instance hosted at Gandi. Gandi must verify that the domain is your own by checking you have administration privilege on it. To perform that, Gandi will check DNS record on the vhost you want to bind to a PaaS instance.
>>> paas_spec = {
'name': 'My PaaS',
'size': 'm',
'type': 'phpmysql',
'datacenter_id': 1,
'vhosts': ['vhost.test.fr'],
'quantity': 0,
'duration': '3m',
'password': 'xxxxxxxxxx',
'--dry-run': True}
>>> ops = api.paas.create(apikey, paas_spec)
[{'attr': ['vhost.test.fr', 'vhost=2e5d8f0899053fffcd3ecf4ac5a6433b'],
'error': 'EC_TXT+EC_MISSINGMANDATORY',
'field': 'vhosts',
'field_type': None,
'reason': 'You must put a TXT value in your zone'}]
The DNS zone must be altered to store tha record like:
10800 IN TXT “vhost=2e5d8f0899053fffcd3ecf4ac5a6433b”
Or, by adding a new virtual host:
>>> api.paas.vhost.create(key, {'paas_id': 1,
'vhost': 'vhost.test.fr',
'--dry-run': True})