Send a request to API
The API use requires an identification as the administration interface. There is 2 ways to log in:
- The username/password couple: it is the login details used to access to the administration interface, an email address and its related alwaysdata password;
- the API key: you can find/generate it from the Profile menu of you customer area.
Examples with curl :
Enter host password for user 'firstname.lastname@example.org':
$ curl --basic --user APIKEY: https://api.alwaysdata.com/v1/account/
Attention to use your API key do not forget the colon (:) after it which makes it clear that the password is not necessary.
There is currently a HTTP header specific to alwaysdata:
|alwaysdata-synchronous||Running queries in synchronous mode||no|
If you access to ressource related to a specific user or account you have to specify it throughout your authentication by stipulate one or several setting(s):
- account: the account you want to access. For example if you have several accounts but want to access to the ressource of a specific account.
- customer: if you have certain permissions on another user account you have to specify its email address.
For example here is a way to access to the FTP users of your mycompany account:
$ curl --basic --user "APIKEY account=mycompany:" https://api.alwaysdata.com/v1/account/
The API currently handles these formats:
- Yaml (only for answer)
The data format you want will be determined by our API in the following order:
- setting in the URI: your request sends in the address the _format setting
$ curl --basic --user APIKEY: https://api.alwaysdata.com/v1/account/?_format=xml
- HTTP headers: Accept and/or Content-Type headers are knowledgeable in your request
$ curl --basic --user APIKEY: --header "Accept: application/xml" https://api.alwaysdata.com/v1/account/
- otherwise the default format: JSON.
As pointed in the introduction the REST concept assumes that each resource has its own URI. Here are, in general, the different possible addresses for a resource:
- list and addition: /ressource/
- liste with filtering: /ressource/?scope=value
- reading, modification, removal: /ressource/id/
- specific operation: /ressource/id/operation/
In this theorical example following keywords have to be replaced:
- ressource : element you access (account, ftp, database, etc.)
- id : ressource unique identifier
- operation : action specific to the involved ressource
Some ressources offers specific actions, as restart a site:
$ curl -d '' --basic --user "APIKEY account=mycompany:" https://api.alwaysdata.com/v1/site/123/restart/