New Remote Plesk REST API for Automation - The Complete Plesk Guide

New Remote Plesk REST API for Automation

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:

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

with your Plesk server hostname.

The response may look like the following:

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

new remote REST API

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:

new remote REST API on Plesk - Plesk RESTful API authentication, Cli, Server

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):

Plesk Server entry points - New remote REST API on Plesk

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.

REST Client - new remote REST API on Plesk

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.

new remote REST API on Plesk - Postman

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:

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):

The response will be the following:

The next step is to install the license key. The end-point /server/license will help you to achieve this:

The successful result is reported with 200 OK HTTP code and the following content:

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:

And this is the API request:

The successful response can also look like the following:

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:

You’ll get the following output:

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.

About

Alexei has been part of the Plesk team since 2005 and is the Plesk Core team's Unit Manager. He's passionate about programming, product development and driving tech teams.
Showing 3 comments
  • Michael
    Reply

    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.

    • Alexei Yuzhakov
      Reply

      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.

  • test11
    Reply

    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.

Leave a Comment

Start typing and press Enter to search