Table of Contents

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:

Please, read the iTop wiki page related to 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:

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:

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

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:

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:

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: