====== REST/JSON services ======
===== Presentation =====
TeemIp provides its own set of WEB services through the REST/JSON interface available by default in iTop. These services enable a remote application to automatize basic IP management tasks:
* get the number of registered IPs in subnets and their status
* automatically create an IP in a subnet
* automatically create an IP in an IP range
* automatically create a subnet in an IP block
* get a DNS zone db file
Please, read the iTop wiki page related to [[https://www.itophub.io/wiki/page?id=LATEST%3Aadvancedtopics%3Arest_json|iTop REST/JSON services]] before implementing TeemIp REST/JSON services.
===== Operation: list_operations =====
The additional operations provided by TeemIp can be listed with the standard //list_operations// command that is already available in iTop.
As a reminder, the syntax of the json_data input is:
{
"operation": "list_operations"
}
The reply will look like:
Array
(
[version] => 1.3
[operations] => Array
(
[0] => Array
(
[verb] => core/create
[description] => Create an object
[extension] => CoreServices
)
[...] Other iTop core services
[7] => Array
(
[verb] => teemip/get_webservices_version
[description] => Provides the WEB services version currently in use
[extension] => TeemIpServices
)
[8] => Array
(
[verb] => teemip/get_nb_of_registered_ips_in_subnet
[description] => Get the number of registered IPs in subnet(s)
[extension] => TeemIpServices
)
[9] => Array
(
[verb] => teemip/pick_ip_address_in_subnet
[description] => Automatically pick and register an IPv4 or IPv6 address in a given subnet
[extension] => TeemIpServices
)
[10] => Array
(
[verb] => teemip/pick_ip_address_in_range
[description] => Automatically pick and register an IPv4 or IPv6 address in a given IP range
[extension] => TeemIpServices
)
[11] => Array
(
[verb] => teemip/pick_subnet_in_block
[description] => Automatically pick and register an IPv4 or IPv6 subnet in a given IP block
[extension] => TeemIpServices
)
[12] => Array
(
[verb] => teemip/get_zone_file
[description] => Generate and provide the text file that describes the specified DNS zones
[extension] => TeemIpServices
)
)
[code] => 0
[message] => Operations: 12
)
===== TeemIp services =====
==== Operation: teemip/get_webservices_version ====
Provides the version of TeemIp specific services currently in use.
Passing the following ''json_data'':
{
'operation': 'teemip/get_webservices_version',
}
... the reply will look like:
Array
(
[code] => 0
[message] => TeemIp WEB Services version running is: 1.1
)
==== Operation: teemip/get_nb_of_registered_ips_in_subnet ====
Get the number of registered IPs in one subnet or in a list of subnets. Answer will contain the following details, for each of the requested subnets:
* Attributes
* Organization name
* Subnet Name
* Subnet IP address
* Mask
* Subnet size
* Number of IPs
* Allocated
* Released
* Reserved
* Unassigned
* Totaly registered
* Free
__Example 1__
Passing the following ''json_data'':
{
'operation' => 'teemip/get_nb_of_registered_ips_in_subnet',
'class' => 'IPv4Subnet',
'key' => array(
'org_id' => 3,
'ip' => '10.129.2.0',
),
'fields' => array(
),
'comment' => '',
}
... will provide the reply:
Array
(
[objects] => Array
(
[IPv4Subnet::6] => Array
(
[code] => 0
[message] => computed
[class] => IPv4Subnet
[key] => 6
[fields] => Array
(
[org_name] => Demo
[name] => HQ-VLAN50
[ip] => 10.129.2.0
[mask] => 255.255.254.0
)
[subnet_size] => 512
[nb_of_ips] => Array
(
[allocated] => 4
[released] => 0
[reserved] => 2
[unassigned] => 12
[total registered] => 18
[free ips] => 492
)
)
)
[code] => 0
[message] => Found: 1
)
__Example 2__
Other forms of "key" may be used, like:
{
'operation' => 'teemip/get_nb_of_registered_ips_in_subnet',
'class' => 'IPv4Subnet',
'key' => "SELECT IPSubnet WHERE org_id = 3",
'fields' => array(
),
'comment' => '',
}
... answer may be, then, much longer:
Array
(
[objects] => Array
(
[IPv4Subnet::5] => Array
(
[code] => 0
[message] => computed
[class] => IPv4Subnet
[key] => 5
[fields] => Array
(
[org_name] => Demo
[name] => GRE-VLAN50
[ip] => 10.128.0.0
[mask] => 255.255.254.0
)
[subnet_size] => 512
[nb_of_ips] => Array
(
[allocated] => 0
[released] => 0
[reserved] => 0
[unassigned] => 0
[total registered] => 0
[free ips] => 510
)
)
... other subnets ...
[IPv6Subnet::19] => Array
(
[code] => 0
[message] => computed
[class] => IPv6Subnet
[key] => 19
[fields] => Array
(
[org_name] => Demo
[name] =>
[ip] => fc01:0:1964:aff::
[mask] => 64
)
[subnet_size] => 1.844674407371E+19
[nb_of_ips] => Array
(
[allocated] => 0
[released] => 0
[reserved] => 0
[unassigned] => 0
[total registered] => 0
[free ips] => 1.844674407371E+19
)
)
)
[code] => 0
[message] => Found: 7
)
=== Error messages ===
TeemIp specific error messages may be:
* //The current user does not have enough permissions for reading data of class //
* //IP addresses cannot be counted within an object of class if target class is not a subnet class.//
==== Operation: teemip/pick_ip_address_in_subnet ====
Pick and register an available IP in a given subnet. The first available IP will be registered unless an offset has been set for this operation in which case the first available IP next to the offset will be taken. The offset is defined in the [[2_x:datamodel:ip-settings#global_ip_settings|Global IP Settings]] for the organization.
The request may specify the attributes to be given to the IP. Similarly, output fields may be specified in the request.
__Example__
Passing the following ''json_data'':
{
'operation' => 'teemip/pick_ip_address_in_subnet',
'class' => 'IPv4Subnet',
'key' => array(
'org_id' => 3,
'ip' => '10.129.2.0',
),
'fields' => array(
'status' => 'reserved',
'comment' => 'Hello',
'requestor_id' => array(
'name' => 'Kahlo',
'first_name' => 'Frida',
),
'short_name' => 'my-test-ip',
'domain_id' => array(
'name' => 'demo.com.',
),
),
'comment' => '',
'output_fields' => 'ip, short_name, domain_name, status',
}
... will provide the reply:
Array
(
[objects] => Array
(
[IPv4Address::42] => Array
(
[code] => 0
[message] => created
[class] => IPv4Address
[key] => 42
[fields] => Array
(
[ip] => 10.129.2.5
[short_name] => my-test-ip
[domain_name] => demo.com.
[status] => reserved
)
)
)
[code] => 0
[message] =>
)
=== Error messages ===
TeemIp specific error messages may be:
* //IP addresses cannot be created within an object of class // if target class is not an IPv4 or IPv6 subnet class.
* //The current user does not have enough permissions for creating data of class //
* //The subnet does not exist//
* //There is no free IP in the subnet (above configured offset, if any)//
==== Operation: teemip/pick_ip_address_in_range ====
Pick and register an available IP in a given IP range. The first available IP will be registered and no offset can be used here.
The request may specify the attributes to be given to the IP. Similarly, output fields may be specified in the request.
__Example__
Passing the following ''json_data'':
{
'operation' => 'teemip/pick_ip_address_in_range',
'class' => 'IPv6Range',
'key' => 22,
'fields' => array(
'status' => 'reserved',
'comment' => 'Hello',
'requestor_id' => array(
'name' => 'Kahlo',
'first_name' => 'Frida',
),
'short_name' => 'my-test-ip',
'domain_id' => array(
'name' => 'demo.com.',
),
),
'comment' => '',
'output_fields' => 'ip, short_name, domain_name, status',
}
... will result into something like:
Array
(
[objects] => Array
(
[IPv6Address::44] => Array
(
[code] => 0
[message] => created
[class] => IPv6Address
[key] => 44
[fields] => Array
(
[ip] => fc01:0:1964:404:a::
[short_name] => my-test-ip
[domain_name] => demo.com.
[status] => reserved
)
)
)
[code] => 0
[message] =>
)
=== Error messages ===
TeemIp specific error messages may be:
* //IP addresses cannot be created within an object of class // if target class is not an IPv4 or IPv6 range class.
* //The current user does not have enough permissions for creating data of class //
* //The IP range does not exist//
* //There is no free IP in the IP range//
==== Operation: teemip/pick_subnet_in_block ====
Pick and register an available subnet in a given IP block. The first available subnet will be registered and no offset can be used here.
The request may specify the attributes to be given to the subnet. Similarly, output fields may be specified in the request.
__Example__
Passing the following ''json_data'':
array
(
'operation' => 'teemip/pick_subnet_in_block',
'class' => 'IPv6Block',
'key' => 15,
'fields' => array(
'name' => 'Vlan - '.$i,
'mask' => '64',
'status' => 'reserved',
'comment' => 'Hello',
'requestor_id' => array(
'name' => 'Kahlo',
'first_name' => 'Frida',
),
),
'comment' => '',
'output_fields' => 'name, ip, mask, status, type, requestor_id',
)
... will provide the following answer.
Array
(
[objects] => Array
(
[IPv6Subnet::181] => Array
(
[code] => 0
[message] => created
[class] => IPv6Subnet
[key] => 181
[fields] => Array
(
[name] => Vlan - 3377
[ip] => fc01:0:1964:407::
[mask] => 64
[status] => reserved
[type] => DC Server LAN
[requestor_id] => 7
)
)
)
[code] => 0
[message] =>
)
=== Error messages ===
TeemIp specific error messages may be:
* //Subnets cannot be created within an object of class if target class is not an IPv4 or IPv6 subnet class//
* //The current user does not have enough permissions for creating data of class //
* //The IP block does not exist//
* //There is no space left for a new subnet in the IP block//
==== Operation: teemip/get_zone_file ====
Get, under standard BIND format, the master db file that describes a DNS zone.
The request specifies the zone, the view it belongs to (if any) and the output order for records: by records or by char.
__Example__
Passing the following ''json_data'':
array
(
'operation' => 'teemip/get_zone_file',
'class' => 'Zone',
'key' => array(
'org_id' => 3,
'name' => 'demo.com.',
'view_id' => 1,
),
'format' => 'sort_by_record',
)
... will give the following text file
Array
(
[objects] => Array
(
[Zone::13] => Array
(
[code] => 0
[message] => computed
[class] => Zone
[key] => 13
[fields] => Array
(
)
[text_file] => $TTL 86400
@ IN SOA ns0.demo.com. hostmaster.demo.com. (
10 ; Serial
900 ; Refresh
600 ; Retry
604800 ; Expire
300 ) ; Negative caching
;
; Name servers
;
;
; IPv4 addresses for the canonical names
;
;
; IPv6 addresses for the canonical names
;
;
; Aliases
;
;
; Mail exchangers
;
;
; Locate services
;
;
; Text
;
)
)
[code] => 0
[message] => Found: 1
)
=== Error messages ===
TeemIp specific error messages may be:
* //No TeemIp zone management extension has been installed//
* //The current user does not have enough permissions for reading data of class Zone//