This document describes how to interface with Installatron Plugin's REST APIs. Examples, for each API, are provided for CLI, curl, and PHP.
See the left sidebar for a complete list of Installatron Plugin 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.)
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 Plugin's APIs all require authentication. The method of authentication depends on the type of user making the API call and their method of calling the API.
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 Plugin API calls is provided by including the appropriate login information to the control panel:
Scope for the curl method is determined by the login used.
PHP authentication for Installatron Plugin API calls is provided by including the appropriate login information to the control panel:
Scope for the curl method is determined by the login used.
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 Plugin 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 Plugin 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 Plugin 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.
The Installatron Plugin 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