Comments on How To Create Remote API Scripts For ISPConfig 3

Hello 

 I want to thank you for this great guide, really helped me lot, 

 

I am just glad it helped someone out.

One thing I wanted to add is the management of crypted passwords. If you wish to import the accounts from another server and have no the list of passwords in plan text you should use the switch

$params = array('_ispconfig_pw_crypted' => 1, 'password' =>'$1$asdasd ....

Thanks for this HowTo.

It might be worth mentioning that the

$soap_location = 'http://localhost:8080/remote/index.php';
$soap_uri = 'http://localhost:8080/remote/';

must be the location of your ISPConfig3 server. So if you have moved the service to a different port then that is the port you must put here. (Also note it is not the apps-vhost port!)

Similarly if you have (as you should) secured your ISPConfig3 service with SSL then the protocol must be set to 'https'.

So if, for example, you are running ISPConfig3 on

https://mydomain.com:10000/index.php

then your soap params become

$soap_location = 'https://localhost:10000/remote/index.php';
$soap_uri = 'https://localhost:10000/remote/';

Probably obvious to most people but it wasn't to me! (I'm new to SOAP), and the

"You should also put in your soap?location and uri, but more than likely you will not have to change this." 

didn't really help me with any clues to what to enter :-(

Thanks

For all of those, who were tired of testing the API and not using php, i got it working with Perls SOAP::Lite Library.

It was quite a pain, read a lot of source, so enjoy the anwser and start to code:

That is a democode to create a website:

#!/usr/bin/env perluse strict;use warnings;#use SOAP::Lite +trace => 'all';use SOAP::Lite;$SOAP::Constants::PREFIX_ENV = "SOAP-ENV";my $params = {};$params->{server_id} = 1;$params->{ip_address} = '*';$params->{domain} = 'apitestdomain.com';$params->{type} = 'vhost';$params->{parent_domain_id} = 0;$params->{vhost_type} = 'name';$params->{hd_quota} = 100000;$params->{traffic_quota} = -1;$params->{cgi} = 'y';$params->{ssi} = 'y';$params->{suexec} = 'y';$params->{errordocs} = 1;$params->{is_subdomainwww} = 1;$params->{php} = 'php-fpm';$params->{stats_type} = 'webalizer';$params->{allow_override} = 'All';$params->{pm_max_requests} = 0;$params->{pm_process_idle_timeout} = 10;$params->{active} = 'y';$params->{traffic_quota_lock} = 'n';$params->{pm_max_children} = 10;$params->{pm_start_servers} = 2;$params->{pm_min_spare_servers} = 1;$params->{pm_max_spare_servers} = 5;$params->{pm_max_requests} = 0;$params->{php_fpm_use_socket} = 'y';my $options = {};$options->{location} = 'https://www.apihost.com:8080/remote/index.php';$options->{uri} = 'https://www.apihost.com:8080/remote/';my $username = 'api';my $password = 'xxxxxxxxxxxxxxxxx';my $client_id = 1;my $client = SOAP::Lite->new(proxy => $options->{location}, %{$options});my $session = $client->call("login", $username, $password);die $session->faultstring if ($session->fault);my $site = $client->call('sites_web_domain_add',    SOAP::Data->name('param0')->value($session->result)->type('string'),    SOAP::Data->name('param1')->value($client_id)->type('int'),    SOAP::Data->name('param2')->value($params)->type('map'),    SOAP::Data->name('param3')->value('false')->type('boolean'));die $site->faultstring if ($site->fault);printf("Site created successfully. ID: %d\n", $site->result);my $logout = $client->call('logout', $session->result);die $logout->faultstring if ($logout->fault);

Since ISPConfig 3.1, you can also use the REST api which returns the results in json format.

 

Examples:

 

Add a DNS zone:

 

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"session_id": "5b5034d3c2e54d79cd641fe53f3cf3d2","client_id": "1","params": {"server_id": 1,"origin": "example.com.","ns": "ns1.example.com.","mbox": "admin.example.com.","serial": 2016090601,"retry": 540, "refresh": 80, "expire": 604800, "minimum": 3600, "ttl": 604800, "xfer": "", "also_notify": "", "update_acl": "", "active": "Y"}}' "https://192.168.1.100:8080/remote/json.php?dns_zone_add" -k

 

Add a database user:

 

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"session_id": "5b5034d3c2e54d79cd641fe53f3cf3d2","client_id": "1","params": {"server_id": 1,"database_user": "c1testdbuser","database_user_prefix": "c1","database_password": "pwdtestdbuser"}}' "https://192.168.1.100:8080/remote/json.php?sites_database_user_add" -k

 

Add a database:

 

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"session_id": "5b5034d3c2e54d79cd641fe53f3cf3d2","client_id": "1","params": {"server_id": 1,"parent_domain_id": 2,"type": "MySQL","database_name": "rest","database_name_prefix": "c1","database_quota": 0, "database_user_id": 7, "database_ro_user_id": 0, "database_charset": "", "remote_access": "n", "active": "y", "remote_ips": ""}}' "https://192.168.1.100:8080/remote/json.php?sites_database_add" -k

In various contexts, the UI allows to filter based on certain values, e.g. finding all email forwards for a specific destination email address.

Is there a function to do this via the REST API? The only method I was able to find is

    public function mail_forward_get($session_id, $primary_id)    {        global $app;        if(!$this->checkPerm($session_id, 'mail_forward_get')) {            throw new SoapFault('permission_denied', 'You do not have the permissions to access this function.');            return false;        }        $app->uses('remoting_lib');        $app->remoting_lib->loadFormDef('../mail/form/mail_forward.tform.php');        return $app->remoting_lib->getDataRecord($primary_id);    }

but there I already have to pass the primary_id of the forwarder :(

Any ideas?

See also the examples and docs on https://git.ispconfig.org/ispconfig/ispconfig3/-/tree/master/remoting_client

This URL gives a 404 :-/

Try this one instead: https://git.ispconfig.org/ispconfig/ispconfig3/-/tree/develop/remoting_client/ — there seems to have been some branch name rewriting.

This page definitely needs to be expanded to cover the parameters and return values of ALL calls accepted by ISPCONFIG 3.2.

The examples for using the remote API are part of the ISPConfig source code. You can find them in any ISPConfig tar.gz archive and also directly on the GIT server: https://git.ispconfig.org/ispconfig/ispconfig3/-/tree/develop/remoting_client