Plesk Onyx 17.8 introduced a new remote REST API. Yes, XML-RPC API is still available, but we recommend using this more simple and convenient REST API from now on. Read on to find out why you should, the main concepts, and the use cases for REST API for automation.
Installation of REST API
You don’t need to install additional components or extensions. REST API is bundled with Plesk Onyx 17.8+ and is therefore ready for immediate use.
REST API Example
Let’s try to make our first call to remote API and see the results. We’ll use “curl” for that reason. REST API has an end-point which provides the Plesk instance info. Here’s the request which you can also execute in a console:
curl -k -u admin:**** -X GET "https://<plesk-host>:8443/api/v2/server"
You need to replace
“****”
with a real password. Note you can even make the request using a secret key instead of a plain password. You should also replace
<plesk-host>
with your Plesk server hostname.
The response may look like the following:
"platform": "Unix", "hostname": "<plesk-host>", "guid": "d62fb896-3ec7-4690-8197-458b4285d5f7", "panel_version": "17.8.11", "panel_revision": "c3fb546fb867ac424d65da14d8b023f11ec0d150", "panel_build_date": "2018-03-01", "panel_update_version": "18", "extension_version": "1.2.0", "extension_release": "54"
As you can see, this is using Plesk 17.8.11 for the Linux platform. The response is in JSON format, which is easy to parse, analyze, and extract the details.
New Remote API Concepts
New remote API for Plesk is based on REST concepts and provides the output in JSON format. There are a lot of articles about REST APIs in general. And it’s become very popular as a standard de facto for building modern APIs. So developers are already familiar with this approach.
API is represented as a bunch of end-points which reflects Plesk business object model. Each end-point may accept the requests using various HTTP methods (GET – for fetching the data, POST – for modifying it). End-points may contain nested resources to scope the actions on particular business object.
Now, API is described using Swagger format in JSON and YAML form. You can access the description by browsing the following URLs:
- https://<plesk-host>:8443/api/v2/swagger.json
- https://<plesk-host>:8443/api/v2/swagger.yml
To open these URLs, you can use a browser, and to see the JSON structure in a pretty format, you can choose to use a browser plugin (like JSONView for Google Chrome, for example).
Swagger scheme is also published at Swagger Hub. Since Plesk is not a SaaS service with static domain name, you can’t use Swagger Hub as a playground to execute API requests on your own server. But later in the “Tools” section, you’ll see other ways you can easily play with API. More info about REST API concepts in this Plesk doc.
REST API Tools
There are a lot of tools and API clients for REST APIs. If “curl” is not enough there are other options.
Integrated Reference & Playground
Plesk REST API comes with the integrated reference and playground. You can access it by browsing the following URL: https://<plesk-host>:8443/api/v2/ where <plesk-host> is a hostname of your Plesk server. The first time you need to enter your Plesk admin credentials. The reference looks like this:
It’s not only the reference, but also an interactive playground.
You can select the method, expand the block to see details and click “Try it out” in the right corner of the block. If there are additional parameters, it’s possible to provide a payload – the “body” of request. You can also customize API request parameters. After, you need to press the big blue button, “Execute” in order to see the results. Here’s how it works for the “/server” end-point (fetching meta information about the server):
The “Response body” field contains the real result of the API call. The integrated reference and playground is the best way to become familiar with REST API in a short period of time.
PhpStorm REST Client
IDEs usually have plugins or integrated REST clients. As an example, we can take a look at PhpStorm – which is probably the most popular IDE for PHP developers. It comes with the integrated REST client (see Tools -> Test RESTful Web Service option).
You need to specify host/port pair and the path. In the example below, I tried to fetch the information about server’s IP addresses.
Don’t forget to provide credentials. There is a small icon with the keys in a left sidebar, which allows to do it.
Making an API call to Plesk using Postman
Another very popular option is Postman. If you have no valid SSL certificate for control panel, you can disable SSL validation in Settings dialog (Preferences -> General tab). You need to type the full URL to end-point (we will check server meta information once again), provide the credentials using “Basic Auth” method and press the big blue button “Send” to submit the request.
If the execution is successful, the result will be demonstrated at the bottom of the screen. Then printed nicely with a syntax highlighting.
Provisioning Scenarios Using Remote API
After the first steps you can be ready to write some automated scenarios using remote API. There could be a lot of various provisioning scenarios. Let’s analyze one of them.
For example, you sell virtual servers with Plesk pre-installed. We assume Plesk is already installed on the server or there’s a ready-to-use image for that. You want to perform post-installation steps if your customer orders a VPS. Here’s what such post-installation steps may look like.
- perform Plesk initialization (to provide customer specific information)
- install a license key
- create a first domain
First, to perform Plesk initialization, you need to make POST request to /server/init end-point. We’ll use “curl” and create a temporary file with payload for convenience. Let’s name it plesk-init.json and put the following content in it:
{
"admin": {
"name": "John Smith",
"email": "[email protected]"
},
"password": "setup",
"server_name": "example.com"
}
Then, perform an API call. If “admin” credentials aren’t set, you can use “root” system user credentials instead (or “administrator” in case of Windows):
curl -k -u root:****** -X POST -d @plesk-init.json "https://<plesk-host>:8443/api/v2/server/init"
The response will be the following:
{
"status": "success"
}
The next step is to install the license key. The end-point /server/license will help you to achieve this:
curl -k -u admin:****** -X POST -d '{ "code": "AX2P00-****" }' "https://<plesk-host>:8443/api/v2/server/license"
The successful result is reported with 200 OK HTTP code and the following content:
{
"status": "success"
}
The last step in our scenario is to create a webspace (domain with hosting). You can create the plesk-domain.json file to store payload temporary and avoid typing it in the command line. Here’s the possible content of the plesk-domain.json file:
{
"name": "example.com",
"hosting_type": "virtual",
"hosting_settings": {
"ftp_login": "ftplogin",
"ftp_password": "ftppassword"
},
"ipv4": ["212.XXX.XXX.XXX"],
"plan": {
"name": "Unlimited"
}
}
And this is the API request:
curl -k -u admin:****** -X POST -d @plesk-domain.json "https://<plesk-host>:8443/api/v2/domains"
The successful response can also look like the following:
{
"id": 1,
"guid": "222c4c4f-168a-4d2f-a867-687123ef8294"
}
You can store GUID in an external system if you need to make an external reference to Plesk business object. Our mission’s accomplished and you are ready to provide the virtual server with Plesk to your end-customer.
One More Thing…
OK, everything’s ready, minus one last step. You may want to send a one-time login link to your customer (buyer of a virtual server with Plesk), and you do it like this:
curl -k -u admin:****** -X POST -d '{ "params": [ "--get-login-link" ] }' "https://<plesk-host>:8443/api/v2/cli/admin/call"
You’ll get the following output:
{
"code": 0,
"stdout": "https:\/\/example.com:8443\/login?secret=lxkmiMfdJzLOBQ6s...",
"stderr": ""
}
The “stdout” property will contain the links – usually two links per one-time login attempt, which you can send to an end customer.
REST API or XML-RPC API?
As you can see, the current version of REST API doesn’t cover as many functions as XML-RPC API. On the other hand, real integrations use a very limited subset of XML-RPC API operations. Because we want to keep REST API simple and useful.
So, the approach of re-implementing every method in REST API doesn’t sound like a good idea to us. The most popular scenarios are already covered by REST API methods. In the end, we’ll continue to increase the functional coverage, but keep API small and simple at the same time.
You can initialize your Plesk remotely, fetch meta information about server (or you /server end-point as a “ping” request). You can manage clients and domains, or even execute the CLI utility over the REST API interface. But ultimately, you can do it all in a much more convenient way compared to XML-RPC API.
with
15 Comments
To use the API, I need to store an admin password in my script or program
I like to at least use a separate administrative account “api” , not “admin” in order to separate affairs.
I created it in Plesk (/admin/admin-alias/list)
Unfortunately, this account does not work with the API.
I get
{
“code”: 0,
“message”: “Can not find client by login ‘api'”
}
The extra account worked with the old API.
The approach is a little bit different. It’s highly recommended to use secret keys instead of admin’s password. See /auth/keys end-point for details. You can create a key, store it and use for future requests.
Hallo,
We are trying to integrate the PLESK with an PHP (CRM) application that we have developed, we whant to integrating the plesk on our application per Iframe or Plesk API .
What ist the best and safe way to integrate plesk via API with external application ?
When loading the iframe plesk tdoes not leave complete, we can not see the menu part of the right side of the plesk and you can not see the top of the plesk where the user can logout.
We can see on the plesk page, that it has the following label on the body, , and if this is the reason why we can not view the complete plesk in our iframe of our application.
We also have another problem, that every time we want to load the plesk page https://domain:8443/login_up.php?success_redirect_url=https%3A%2F%2F%2Fdomain.of%3A8443%2F in our iframe redirects us, sometimes to full screen, as you can see it shows us success_redirect_url, we don’t know if it is ´por this reason that takes us out of the iframe and then presents us to full screen in the same page of the application we are doing, this doesn’t do it every moment, it does it sporadically, but it shouldn’t do it. exists or can be changed not to pass the message of success_redirect_url, or by default the plesk has to perform this action. ?
If we place the url https://domain:8443/ alone in the iframe does not work for us, we have to place it as url https://domain:8443/login_up.php?success_redirect_url=https%3A%2F%2Fdomain%3A8443%2Fsmb%2Ffile-manager%2Flist%2FdomainId%2F32 as it is so placed by the plesk.
In general integration of Plesk interface via iframe is highly discouraged. Plesk API is more preferable way, but requires more efforts.
P.S. Blog post is not intended for long discussions. https://talk.plesk.com/ is more suitable place.
Hello, great to have the REST API.
I was wondering, if there is a way to get the “domain-alias”-list
by using the REST API.
It seems, that this function is missing (?)
Unfortunately there is no convenient way to retrieve the list of domain aliases. We will consider adding this functionality in the future versions of REST API.
I hope you consider adding REST API domain alias listing support sooner rather than later!
Hi. Can you help please? I need to get a Create a REST api end point and pass the url to a payment gateway company so that after every transaction, the leave me a method in the end point. How do I set about creating an end point and how do I get the url of that end point?
Hey Dipo, have you been in touch with our support team regarding this?
Hi, I have created a new client using “POST” api/v2/clients with no issues but when getting the client details using “GET” api/v2/clients its missing few properties values mentioned below,
“external_id”: “”, “description”: “”,”locale”: “”
Sample data below,
POST: Body
{
“created”: “2019-09-02”,
“name”: “Demoname”,
“company”: “Demo”,
“login”: “[email protected]”,
“status”: 0,
“email”: “[email protected]”,
“locale”: “en-US”,
“owner_login”: “demo”,
“external_id”: “link:123456”,
“description”: “Demo description”,
“password”: “setup”,
“type”: “customer”,
}
GET: Response
{
“id”: 9
“created”: “2019-09-02”,
“name”: “Demoname”,
“company”: “Demo”,
“login”: “[email protected]”,
“status”: 0,
“email”: “[email protected]”,
“locale”: “”,
“guid”: “1234-dsfju23480”
“external_id”: “”,
“description”: “”,
“type”: “customer”,
}
i also tried PUT method to update the value but its not working.
Can anyone direct me where i am missing
I was wondering where I can ask for new functionality to be added?
e.g. I need a call so that I can see which GIT branch my client is on and if necessary switch branches through a call. I love the webhook functionality as that allows for me to implement automatic integration. This switching branches would allow for a whole new interaction.
Hey raja, thanks for your engagement, have you tried raising this in our User Voice? https://plesk.uservoice.com/forums/184549-feature-suggestions
if you are a partner, how you link your partner API to your plesk admin host panel.
Hey Jalal,
Partner API refers to the KA account and licensing operations, not to the Plesk panel.
For Plesk, there is another kind of API. You may refer to the documentation links below:
Partner API 1.0 and 3.0
https://docs.plesk.com/en-US/obsidian/partner-api-1.0/introduction.77524/
https://docs.plesk.com/en-US/obsidian/partner-api-3.0/introduction-to-key-administrator-partner-api-30.77827/
Plesk API:
https://docs.plesk.com/en-US/obsidian/api-rpc/79359/
Feel free to contact our support if you run into issues 🙂
I love that you have created this REST API but for me it’s a little too limited. I would really like to be able to manage email addresses on domains.
I disagree that it would be a bad idea to replicate all functionality of the XML API in the REST one. I think that’s necessary or ultimately people will just stick to the old XML one.
REST is modern. Please build it out to be as flexible as the XML version!