Send a request to API

Identification

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 :

$ 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 to use your API key do not forget the colon (:) after it which makes it clear that the password is not necessary.

Options

There is currently a HTTP header specific to alwaysdata:

Related ressources

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/

Data format

The API currently handles these formats:

• JSON (by default)
• XML
• HTML (only for answer)

Experimental:

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

URIs

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

Actions

Some ressources offers specific actions, as restart a site:

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