Site API¶

Introduction¶

The Gandi Site API provides a set of remote requests to manage your sites. Gandi sites are created using a website builder Provider. Our API actually uses basekit.

Connect to the API server¶

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

python
php
nodejs
perl
ruby
C

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

Site Management¶

Working with domains not registered at Gandi¶

If you are not using the Gandi DNS or you did not register your domain at Gandi, you can also run a Site 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 site.

>>> site_spec = {
    'name': 'My Site',
    'package': 'professional',
    'vhosts': ['vhost.test.fr', 'bk-site.net'],
    '--dry-run': True}
>>> ops = api.site.create(apikey, site_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 in this fashion to store the new record:

10800 IN TXT "vhost=2e5d8f0899053fffcd3ecf4ac5a6433b"

List all your sites¶

To obtain a list of the sites you own, just call the site.list() method:

>>> api = xmlrpc.client.ServerProxy('https://rpc.gandi.net/xmlrpc/')
>>> api.site.list(apikey)
[]

Count your sites¶

To count the sites you own, just call the site.count() method:

>>> api.site.count(apikey)
0

Get info on a site¶

Retrieve info on your first instance with method site.info() method:

>>> api.site.info(apikey, 1)

Create a site¶

To create a site, use the site.create() method.

The method accepts a dictionnary of values describing the new site, such as

website name
provider used
a list of virtual hosts
the website duration

>>> site_spec = {
    'name': 'My Site',
    'provider': 'basekit_whitelabel',
    'vhosts': ['example.bk-site.net'],
    'duration': '3m'}
>>> op = api.site.create(apikey, site_spec)
>>> op['type']
'sitebuilder_create'

After issuing the site creation order to the Gandi Site API, an Operation will be created on the server-side. You will have to wait for the Operation to finish before you can edit your website.

>>> import time
>>> while op['step'] not in('DONE', 'ERROR'):
        time.sleep(1)
        op = api.operation.info(apikey, op['id'])
>>> op['step']
'DONE'
>>> site_id = api.site.list(apikey, {'name': 'My Site'})[0]['id']

Edit the web site¶

Once site.create() has succeeded and the site is created, you may retrieve an edition url via the method site.info().

It will redirect you to a UI you may use to edit your site.

>>> api.site.info(apikey, site_id)['edit_url']

Manage Virtual Hosts¶

During a website creation it is mandatory to provide it with a list of virtual host URLs.

Every Provider comes with a parking domain where you can declare a subdomain to host your website. There are a few restrictions about the name, but the main one is: the subdomain is unique. first-in, first-served.

You can bind your site on any number of virtual host URLs using the vhosts key in this API (see SiteCreate, SiteUpdate or SiteReturn). You can host your web site on gandi domains without having to alter DNS entries and with any domain names (see site-api-dns-check).

Furthermore, the vhosts orders is important to set or retrieve the preferred vhost. The preferred vhost is used for SEO and is also retrieved in the SiteListReturn.

How to add the virtualhost “www.mydomain.fr” to the previous site:

# add the virtual host www.mydomain.fr to the domain
>>> vhosts = ['www.mydomain.fr', 'example.bk-site.net']
>>> op = api.site.update(apikey, site_id, {'vhosts': vhosts})
>>> ops[0]['type']
'sitebuilder_update'

Important

It is required to keep the site attached to the Provider domain in order to edit the site.

Upgrade to another offer¶

Sites can be upgraded from one offer/package to another but they can not be downgraded from one offer to another, this is a limitation to keep in mind.

You can access the offers using the methods catalog.list() or site.package.list():

>>> # Check the current site offers prices
>>> api.catalog.list(key, {'product': {'type': 'site'}})
>>> # Retrieve list of offers from basekit_whitelabel
>>> api.site.package.list(key, {'provider': 'basekit_whitelabel'})

To obtain the next offer in a package you can also use the ‘>name’ filter

>>> package = api.site.package.list(key, {'provider': 'basekit_whitelabel', '>name': 'personal'})[0]
>>> package
{'name': 'professional', 'provider': 'basekit_whitelabel'}

You can also get a quote for this operation.

>>> descr = "{provider}_{name}".format(**package)
>>> api.catalog.list(key, {"product": {"type": "site", "description": descr}, "action": {"name": "update"}})

See the Gandi Catalog API for more usage.

Use of the site.update() is free for every except when upgrading from a package to another.

Delete a site¶

To delete an instance, use the site.delete() method:

>>> op = api.site.delete(apikey, site_id)
>>> op['type']
'sitebuilder_delete'

Gandi

Table of Contents

Previous topic

Next topic

Site API¶

Introduction¶

Connect to the API server¶

Site Management¶

Working with domains not registered at Gandi¶

List all your sites¶

Count your sites¶

Get info on a site¶

Create a site¶

Edit the web site¶

Manage Virtual Hosts¶

Upgrade to another offer¶

Delete a site¶

Gandi

Quick search

Table of Contents

Previous topic

Next topic

Site API¶

Introduction¶

Connect to the API server¶

Site Management¶

Working with domains not registered at Gandi¶

List all your sites¶

Count your sites¶

Get info on a site¶

Create a site¶

Edit the web site¶

Manage Virtual Hosts¶

Upgrade to another offer¶

Delete a site¶