This document describes how to interface with Installatron Server's REST APIs. Examples, for each API, are provided for CLI, curl, and PHP.
See the left sidebar for a complete list of Installatron Server APIs, and at the bottom of the sidebar are a number of appendices with more information about related topics.
There are multiple elements to an API request:
Installatron APIs use only three HTTP methods:
Check the second line of an API's documentation to find the appropriate HTTP method to call that API.
Note that in Installatron's APIs:
• All views use GET.
• All creates, edits, and miscellaneous actions use POST.
• All deletes use DELETE.
The command refers to the API you're calling. For example:
The commands are also found on the second line of each APIs documentation page.
Headers carry additional details about the request and the expected response. Most HTTP requests include two or three headers, depending on the specific API. (API calls made over CLI do not use a header.)
The X-API-Key header is used to authenticate requests to the Installatron REST API. It should be set to the key= or key2= value configured in /usr/local/installatron/etc/settings.ini. (See the Authentication section below.)
Most Installatron REST API endpoints require an Accept header set to "application/json", indicating that the API response is expected to be formatted in JSON:
All Installatron REST API endpoints also support the X-HTTP-Method-Override header, which overrides the HTTP method (e.g., "POST", "GET", "DELETE") in environments where certain methods might be restricted or unsupported, by tunneling the desired method through a standard POST request:
The Content-Type header specifies the format of the data in the body of an HTTP request. Installatron REST API endpoints typically expect this to be "application/json", indicating that the request body is JSON-formatted. Alternatively, "application/x-www-form-urlencoded" is also supported for key-value pair data, but using JSON is recommended:
See the examples on each APIs documentation page for use of these headers.
These are the values that customize the API call.
For example, here are some parameters, and example values, for the POST /browser/{id}/install API:
See each API page for a full list of available parameters and details on their use.
When you bring all these elements together your API request looks like this for CLI:
Like this for curl:
And for PHP:
Installatron Server's APIs all require authentication. Authentication is provided by either a login to CLI, for the CLI API, or by an "X-API-KEY" header parameter for the curl and PHP APIs.
Your login to CLI is the authentication for Installatron CLI API calls. You must be logged into CLI as the server's root user to access the Installatron APIs.
curl authentication for Installatron Server API calls is provided by adding this header to your API call:
Tip: During installation of Installatron Server it generates an IS licensing key which you can find, after installation, in this file:
/usr/local/installatron/etc/settings.ini
PHP authentication for Installatron Server API calls is provided by this header line:
Tip: During installation of Installatron Server it generates an IS licensing key which you can find, after installation, in this file:
/usr/local/installatron/etc/settings.ini
Some APIs don't require any parameters (eg. /tasks) but most APIs have some mix of optional and/or required parameters which configure the API call.
For example, here are some parameters for the POST /browser/{id}/install API:
See each API page for a full list of available parameters and details on their use.
The format used by the parameters depends on the method used to call the API:
For a CLI call to an Installatron Server API the parameters follow directly after the --cmd {command}, and are in the form:
The earlier example parameters therefore becomes this in their final CLI form:
For a curl call to an Installatron Server API the parameters are provided with the -d configuration parameter, formatted as a JSON package.
The earlier example parameters therefore becomes this in their final curl form:
For a PHP call to an Installatron Server API the parameters are provided with the CURLOPT_POSTFIELDS => option, formatted as a URL-encoded JSON package.
PHP has a function to automatically format JSON from a PHP array so the earlier example parameters become this in their final PHP form:
The response from all APIs, and via all methods, is a JSON structure of this general form if the result is a single value:
Or if the response is an array of JSON objects then the format will be:
Detailing the structure of each API's response is left to each API page but we can briefly look at the other top-level values:
A boolean ("true" or "false") that tells you whether the task was successful.
|
Installatron utilizes standard HTTP response codes to signify the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed due to the information provided (e.g. a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with Installatron's processing of the request. |
|
This status value is a mirror of HTTP status code value that is found in the header of all responses from the server. It is included here for convenience.
More specific HTTP codes associated with each API are found in the Response section of each API's documentation.
Most APIs will return an Installatron error code (errcode) with a more precise explanation for failure, when failure occurs.
For example, here are the possible errcodes returned by the POST /browser/{id}/install API:
status code 400
---------------
empty_argument_bkloc
empty_argument_user
invalid_argument_content
invalid_argument_email
invalid_argument_language
invalid_argument_login
invalid_argument_passwd
invalid_argument_sitetagline
invalid_argument_sitetitle
invalid_argument_version
invalid_argument_{id}
invalid_argument_application
invalid_argument_autobk_custom_daily
invalid_argument_autobk_custom_weekly
invalid_argument_autobk_custom_monthly
invalid_argument_autobk_schedule
invalid_argument_bkloc
invalid_argument_url
invalid_argument_url_alreadyexists
invalid_argument_url_rootonly
invalid_argument_version
invalid_argument_version_unmetrequirements
status code 403
---------------
invalid_api_key
invalid_argument_user
status code 500
---------------
failed_database_create
failed_filesystem_permissionEach API's possible http response codes are detailed on each API's page, in their Response sections.
If the error defined by the errcode value refers to a field value then the internal ID of that field will be included here.
A field, in Installatron parlance, is an input presented to the user when performing a task. For example, when installing an application the login (the administrator's username to use for the new application), passwd (the password that goes with the login), and the administrative user's email address are all fields that are common to most applications. The list of fields an application uses varies from application to application and can be found using the GET /browser/{id} API.
A generic message from Installatron.
This should not be used to determine success or failure of the API call: instead, use result, status, and errcode.
When the API returns an array in the data[] portion of the response (eg. /browser), total_count will show the number of entries in the full result set.
When the API returns an array in the data[] portion of the response (eg. /browser), has_more is "true" when the last entry shown in the response is not the last entry in the full result set.
data can be one of three types:
The Response from all APIs, for all methods, is a JSON package that includes:
The first three of these values are used to handle errors from Installatron's API calls.
Now that you've seen how the Installatron Server APIs work your next step is to add users to the Installatron Server database. This is achieved using the POST /users API.
For example, to add a single user to the database, named "useraccountname":
The webspace and FTP login referenced in this example must already be provisioned and be working -- for the above example user, this would mean that if we loaded "http://website.com" into a web browser we expect it to load the files found at:
ftps://exampleuser:examplepassword@website.com/public_html
If "http://website.com" does not resolve through a public DNS query then you must define vhost_ip and give it the IP address for website.com.
The next step is to install a test instance of WordPress to one of the user's domains using the POST /browser/{id}/install API:
This example will install "WordPress" to the URL of "https://website.com/blog/" of the user "useraccountname". It will give an administrative username of "admin123", password of "password123", and the site a title of "My Blog".
And then you could load https://website.com/blog (for this example) into a web browser to confirm that the new WordPress website is working.
If the user's domain situation changes -- for example, to add a second subdomain -- then you must let Installatron Server know about the change using the using the POST /users/{id} API:
While the Admin Installatron user can log into the Installatron Server GUI through the login prompt at https://{SERVER_IP}, all other users are sent to the GUI using the GET /users/{id}/login API:
The response from this API call is a JSON package of the following form:
You can then forward the user to the URL in data.
The Installatron Server API v2 gives you control over absolutely every aspect of Installatron. We recommend quickly browsing through each API page to get a sense of the commands that are available, but then you can come back to the pages when you have particular needs.
If you have any questions or comments about the APIs or this documentation please feel free to contact us via Installatron Tickets.
- The Installatron Team