Envoyer une requête à l'API

Identification

L'utilisation de l'API nécessite une identification, à l'instar de l'interface d'administration. Il est possible de s'identifier de 2 manières différentes :

• le couple identifiant/mot de passe : ce sont les identifiants utilisés pour accéder à l'interface d'administration, donc une adresse email et son mot de passe alwaysdata associé ;
• la clé API : vous pouvez la trouver/générer à partir du menu « Profil » de l'administration.

Exemples avec curl :

$ curl --basic --user foobar@example.org https://api.alwaysdata.com/v1/account/

Enter host password for user 'foobar@example.org':

$ curl --basic --user APIKEY: https://api.alwaysdata.com/v1/account/

Attention, pour l'utilisation de votre clé API, n'oubliez pas les deux points (:) après celle-ci, ce qui permet de préciser que le mot de passe n'est pas nécessaire.

Options

Il existe actuellement une en-tête HTTP spécifique à alwaysdata :

Ressources liées

Si vous accédez à des ressources liées à un utilisateur ou un compte spécifique, vous devez le spécifier lors de votre authentification en spécifiant un ou plusieurs paramètre(s) :

• account : il s'agit du compte auquel vous désirez accéder. Si par exemple vous avez plusieurs comptes mais souhaitez accéder à une ressource d'un compte précis.
• customer : si vous disposez de certaines permissions sur un autre compte utilisateur, alors vous devez spécifier son adresse email.

Par exemple, accédez aux utilisateurs FTP de votre compte mycompany de cette manière :

$ curl --basic --user "APIKEY account=mycompany:" https://api.alwaysdata.com/v1/account/

Format des données

Actuellement, l’API gère ces différents formats :

• JSON (par défaut)
• XML
• HTML (pour la réponse uniquement)

Expérimental :

• Yaml (pour la réponse uniquement)

Le format des données que vous désirez sera déterminé par notre API selon cet ordre :

• paramètre dans l'URI : votre requête envoit dans l'adresse le paramètre _format

$ curl --basic --user APIKEY: https://api.alwaysdata.com/v1/account/?_format=xml

• en-têtes HTTP : les en-têtes Accept et/ou Content-Type sont bien renseignées dans votre requête

$ curl --basic --user APIKEY: --header "Accept: application/xml" https://api.alwaysdata.com/v1/account/

• sinon, le format par défaut : JSON.

URIs

Comme indiqué dans l'introduction, le principe REST suppose que chaque ressource dispose de sa propre URI. De manière générale, voici les différentes adresses possibles pour une ressource :

• liste et ajout : /ressource/
• liste avec filtrage : /ressource/?champ=valeur
• lecture, modification, suppression : /ressource/id/
• opération spécifique : /ressource/id/operation/

Bien entendu, dans cet exemple théorique, les mots-clés suivant doivent être remplacés :

• ressource : élément auquel vous accédez (account, ftp, database, etc.)
• id : identifiant unique de la ressource
• operation : action spécifique propre à la ressource concernée

Actions

Certaines ressources proposent des actions spécifiques, comme par exemple redémarrer un site :

$ curl -d '' --basic --user "APIKEY account=mycompany:" https://api.alwaysdata.com/v1/site/123/restart/