Working with API

From ISPWiki

Jump to: navigation, search

This document covers the control panels' APIs. You need to be logged in with the appropriate privileges to call a function.

Contents

Authentication methods

Session unique ID authentication

You can use this method when working with a control panel through your web browser.

Access the link 

https://IP-address/manager/ispmgr?out=xml&func=auth&username=user_name&password=пароль

The control panel will return either an error message or the following XML document: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
<auth id="session id"/>
</doc>

Specify this session id in the auth parameter to pass to every call to the control panel. A session id is valid during one hour. This period over, you will have to get authorized again. 

https://IP-address/manager/ispmgr?auth=session_id&out=xml&func=function&parameter1=value&parameter2=value...

In the URL above a control panel's name may be as follows:

  • ispmgr - ISPmanager
  • billmgr - BILLmanager
  • vdsmgr - VDSmanager
  • dsmgr - DSmanager
  • dnsmgr - DNSmanager
  • ipmgr - IPmanager

authinfo authentication

This method can be used for remote function calls. You need to add the authinfo parameter and specify a login and password there to call a function: 

https://IP-address/manager/ispmgr?authinfo=admin1:mypasswd&out=xml&func=function&parameter1=value&parameter2=value...

You must send the authinfo parameter with each call to the control panel.

Trusted IP-addresses authentication

This method can be used for remote calls from a specific IP-address. For example, a billing system is installed on the server and requests the the information about traffic or dick space consumption, number of WWW domains, and so on at regular intervals. This method allows specifying the line below in the configuration file, rather than going through the authentication procedure. 

TrustIP IP-address user

where "IP-address" is an IP address of the server from which requests to the control panel will be sent. "User" is an optional parameter that determines a user name to access the control panel. If it is not specified, requests will be processed with the root privileges.

ISPmanager local function calls

This method can be used for local calls from external programs and scripts. Let's consider a call to the control panel from a custom script that is executed via cron at regular intervals. The control panel traces UID of the process that made a request and processes it with privileges of the user who has this UID. No other authentication data are required.

Key authentication

This method allows using the administrator's login or password.

A key is a random line at least 16 symbols long, such as 1234567890qwertyuiop

The username is "John".

A server administrator may use any of the above authentication methods and execute the following request: 

https://URL/ispmgr?out=xml&func=session.newkey&username=vasya&key=1234567890qwertyuiop

Either OK or an error message will return.

If OK was returned, the user will be redirected to 

https://URL/ispmgr?func=auth&username=vasya&key=1234567890qwertyuiop

Clicking the link will authorize the user and remove the key.

  • You may specify the key from any IP-address. After the user gets access to the control panel, this IP-address will bind to the session.
  • The key can be used only once.
  • Access from any IP-address.

HTTP or HTTPS?

To transfer passwords and session IDs through HTTP is considered potentially insecure. That's why the control panel checks that IP-address of the request host matches that of the server where it is installed. If yes, in case of the local call, HTTP is allowed. Otherwise, only HTTPs can be used. When calling the control panel through HTTP, the error message will be returned.

Calling ISPmanager function with privileges of another user

To call an ISPmanager function with privileges of another user, add su=user_name to the URL. Server administrators can call functions with privileges of any user, resellers can do so with privileges of their user accounts. All other users cannot use this method.

Getting a list of WWW-domains in ISPmanager

Following is an example on how to get a list of WWW domains. You can call all other functions in the same manner. Only a local call is considered in this example.

The fetch command 

fetch -q -o - "http://IP-address/manager/ispmgr?out=xml&func=wwwdomain"

The curl command 

curl -k -s "http://IP-address/manager/ispmgr?out=xml&func=wwwdomain"

Perl

If you are using Perl, install the LWP library. For working with XML documents you need the XML::LibXML library. 

#!/usr/bin/perl -w
use CGI::Carp qw(fatalsToBrowser);
print "Content-type: text/html\n\n";
 
use LWP::UserAgent;
use XML::LibXML;
 
my $result;
 
# Create a pseudo-browser that will run as MSIE and send the request
$ua = LWP::UserAgent->new;
$ua->agent("Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)");
my $req = HTTP::Request->new(POST => 'https://IP-address/manager/ispmgr');
 
$req->content("authinfo=login:password&out=xml&func=wwwdomain");
 
my $res = $ua->request($req);
 
# Check the result
if ($res->is_success) {
	$result = $res->content;
} else {
	die $res->status_line."\n";
}
 
# The $result variable contains either an XML document with the list of WWW domains,
# or an error message
 
my $parser = XML::LibXML->new();
my $doc = $parser->parse_string( $result );
my $root = $doc->documentElement();
 
# Get the list of WWW domains
my @sites = ();
for( $root->findnodes( "elem/name" ) ){
	push @sites, $_->textContent;
}
 
# Display the result
for( sort @sites ){
	print $_."<br>\n";
}


PHP

PHP enables to use URL like standard files. The DOM XML library is used for processing XML documents: 

<?php
   $result = "";
   $fh = fopen( "http://127.0.0.1/manager/ispmgr?out=xml&func=wwwdomain", "r" );
   while( $data = fread( $fh, 4096 ) ){
     $result .= $data;
   }
   fclose( $fh );
 
   // The $result variable contains either an XML document with the list of WWW domains,
   // or an error message
 
   if( $doc = domxml_open_mem( $result ) ){
      $root = $doc->document_element();
      for( $elem = $root->first_child(); $elem; $elem = $elem->next_sibling() ){
         for( $node = $elem->first_child(); $node; $node = $node->next_sibling() ){
            if( $node->node_name() == "name" ){
               echo $node->get_content();
               echo "\n";
            }
         }
      }
   }
?>

Python

For accessing a URL using Python you will need the urllib2 library. Use the xml.dom.minidom library for working with XML documents. 

#!/usr/bin/env python
# -*- coding: utf-8 -*-
 
from urllib2 import urlopen
from xml.dom import minidom
 
print "Content-type: text/html\n\n"
res = urlopen('http://127.0.0.1/manager/ispmgr?func=wwwdomain&out=xml')
 
# The res variable contains either the XML document with the list of WWW domains, 
# or an error message
 
xmldoc = minidom.parse(res)
 
# Get the list of WWW domains and display its result
 
for node in xmldoc.getElementsByTagName('elem'):
        for name in node.getElementsByTagName('name'):
                print ('%s<br>' % name.firstChild.nodeValue)


The mgrctl utility

Alternatively, you can use the internal utility mgrctl that directly calls a control panel (it does not depend on the web-server). This is a more preferable means.

Output of the function results

Output can be generated in XML, JSON and text format.

If you wish to receive output results in a specific format, specify the out=format_name parameter.

The out parameter can have one of the following values:

  • xml - data structures in XML will be generated.
  • devel - similar to XML, but the document will contain data describing the user's interface.
  • text - data structures in the text format will be generated
  • json - data structures in JSON will be generated. More information can be found here.

If the out parameter is missing, the data are considered to be used by the browser and are outputted into html.

XML output format

To generate XML data, add the out=xml parameter to the control panel's query. The result will vary depending on a function you want to call. Thus, if you receive a list of elements, the function returns an XML document that contains the list of XML nodes, one per element. Each node, in its turn, consists of a set of nodes determining parameters of this element. For example, when requesting a list of WWW domains from the control panel, the output will be as follows: 

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=xml"
<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>
		<name>foo.org</name>
		<owner>user</owner>
		<ssl/>
		<php/>
		<ssi/>
	</elem>
	<elem>
		<name>mydomain.com</name>
		<owner>user2</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>rotate.com</name>
		<owner>alm</owner>
		<ssl/>
		<php/>
	</elem>
	<elem>
		<name>test.com</name>
		<owner>john</owner>
		<php/>
		<cgi/>
	</elem>
	<elem>
		<name>test.net</name>
		<owner>user</owner>
	</elem>
</doc>

When calling a function that returns the element's parameters, for example, while editing or viewing this element, the control panel will return an XML document with a list of XML-nodes corresponding to the element's parameter. For example, when viewing the WWW domain's properties form we'll see something like this: 

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=xml"

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>

or the error message 

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=xml"

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>abrakadabra not found.</error>
</doc>

When calling a function that performs an action, such as deletion of WWW domain, the control panel will return a successful XML document: 

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=xml"

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>

or the error message 

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=xml"

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>abrakadabra not found.</error>
</doc>

Text output format

To get data in a text format, add the out=text parameter to the control panel's query. The result will vary depending on a function you want to call. Thus, if receiving a list of elements, the function returns a list of strings, each string corresponding to an element and consisting of a set of parameters of that element. For example, when requesting a list of WWW domains, the result will be as follows : 

# fetch -qo - "http://localhost/manager/ispmgr?func=wwwdomain&out=text"

name=foo.org owner=user ssl php ssi
name=mydomain.com owner=user2 php cgi
name=rotate.com owner=alm ssl php
name=test.com owner=john php cgi
name=test.net owner=user

When calling a function that returns a set of element's parameters, for example, when viewing or editing an element, the control panel will return the list of element's parameters, one per line. For example, when viewing the WWW domain properties form, we'll see: 

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.edit&elid=mydomain.com&out=text"

elid=mydomain.com
domain=mydomain.com
alias=www.mydomain.com
ip=123.45.67.89
owner=user
php=phpcgi
admin=webmaster@mydomain.com
index=index.php index.htm
cgi

When calling a function that performs an action, such as deletion of a WWW domain, if a success the control panel will return the followings 

# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=mydomain.com&out=text"
OK

or the error message 


# fetch -qo - "http://127.0.0.1/manager/ispmgr?func=wwwdomain.delete&elid=abrakadabra&out=text"
ERROR: abrakadabra not found.

Procedure of describing the functions

Functions are described according to the following structure:

Function: a function's name to be transferred in the func parameter.

Parameters: a list of parameters and their brief description. If a function has no parameters, they are not specified. Parameters are transferred in the format parameter=value.

Result: results may vary depending on the function being requested:

List of elements (table)

The XML document will be as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>element's parameters on the list</elem>
	<elem>element's parameters on the list</elem>
	...
	<elem>element's parameters on the list</elem>
</doc>

Result: parameters of an element are only described. These are one or several XML-nodes with all possible attributes and values. For example: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elem>
		<name>foo.org</name>
		<admin>foo_admin</admin>
		<php/>
		<ssi/>
		<user used="1" limit="10"/>
		<disk used="0" limit="10"/>
		<traf used="3542" limit="8192"/>
	</elem>
	<elem>
		<name>example.com</name>
		<admin>example</admin>
		<cgi/>
		<php/>
		<ssi/>
		<frp/>
		<user used="5" limit="50"/>
		<disk used="39" limit="50"/>
		<traf used="1084" limit="4096"/>
	</elem>
</doc>

List of object's parameters (form)

The XML document will be as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>object unique identifier</elid>
	object parameters
</doc>

Result: the object's parameters are only described. These are one or several XML nodes with all possible attributes and values that describe properties of that object. For example: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<elid>example.com</elid>
	<name>example.com</name>
	<gid>1001</gid>
	<alias>www.example.com test.example.com</alias>
	<cgi/>
	<phptype>phpcgi</phptype>
	<ssi/>
	<frp/>
	<sslport>443</sslport>
	<alluser>50</alluser>
	<shelluser>5</shelluser>
	<domain>1</domain>
	<base>3</base>
	<traf>4096</traf>
	<disklimit>50</disklimit>
</doc>

Successful operation (action)

When creating, changing, removing, enabling or disabling an object, the XML document will be as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok/>
</doc>

If the web-server needs to be rebooted 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<ok>restart</ok>
</doc>

To reboot the web-server click the link below: 

http://IP-address/manager/ispmgr?out=xml&func=restart

Error message

If an error occurred while processing your request, the XML document will be as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<doc>
	<error>Error message.</error>
</doc>

For more information, please read the article Error codes.

List of functions and parameters

Every control panel is provided with Documentation where you can find description of their functions and parameters


Alternatively, you can perform operations through the web browser and learn the request that performs you action in the control panel's log.

Retrieved from "http://en.ispdoc.com/index.php/Working_with_API"
Was this helpful? Yes | No
Views