New Remote Plesk REST API for Automation

Plesk is available in Cloud Server Plesk.Contact us to find out our latest offers!

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://: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 with your Plesk server hostname.

The response may look like the following:

{

    "platform": "Unix",

    "hostname": "",

    "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://:8443/api/v2/swagger.json
  • https://: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 on Plesk - Swagger

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://:8443/api/v2/ where 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):

new remote REST API on Plesk - Plesk Server entry points

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.

new remote REST API on Plesk - REST Client

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:

{

  "admin": {

    "name": "John Smith",

    "email": "john-smith@example.com"

  },

  "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://: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://: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://: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://: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.

The post New Remote Plesk REST API for Automation appeared first on Plesk.

Plesk is available in Cloud Server Plesk.Contact us to find out our latest offers!

Comments are closed.

>
WhatsApp chat WhatsApp us