User Tools

Site Tools


2_x:integrate:rest_json

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 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 <class specified in the request>
  • IP addresses cannot be counted within an object of class <class specified in the request> 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 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 <class specified in the request> if target class is not an IPv4 or IPv6 subnet class.
  • The current user does not have enough permissions for creating data of class <class specified in the request>
  • 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 <class specified in the request> if target class is not an IPv4 or IPv6 range class.
  • The current user does not have enough permissions for creating data of class <class specified in the request>
  • 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 <class specified in the request> if target class is not an IPv4 or IPv6 subnet class
  • The current user does not have enough permissions for creating data of class <class specified in the request>
  • 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
2_x/integrate/rest_json.txt · Last modified: 2020/08/11 14:17 by cnaud