Envoyer une requête à l'API
Version | URL | Doc |
---|---|---|
1.0 | https://api.alwaysdata.com/v1/ | https://api.alwaysdata.com/doc/ |
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 :
En-tête | Description | Valeur par défaut |
---|---|---|
alwaysdata-synchronous | Exécution des requêtes en mode synchrone | no |
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 :
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 envoie 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/