rs-cmdb documentation

Dies ist eine alte Version des Dokuments!

rs-cmdb API documentation

HTTP Request methods

rs-cmdb REST API uses standard HTTP methods as described in the table below

Method Action Notes
GET read show object information
POST create create objects
PUT write change object attributes
PATCH change special predefined changes at objects
DELETE delete delete objects

Request structure

<HTTP_METHOD> /rest/<IF_NAME>/<object>[/...] HTTP/1.1

Output format

rs-cmdb REST API supports JSON format.
Typically, the output contains the requested data only. For debugging purposes additional meta information can be delivered by switching it on in the interface configuration.

Authentication

API uses a token for each session to manage the access to the interface. Receiving a token needs authentication with a pre shared key (PSK) and a valid username with password. Authentication is done via “authorization” HTTP header. The received token must be delivered in each request as “token” in the HTTP header. Exceptional, the token can be delivered as plain text instead of embedding it in JSON.

PSK and further parameters have to be aligned in the interface (IF) definition.

Method URL Notes
POST /rest/{IF}/token/{PSK} log on to the API and returns the token
GET /rest/{IF}/token return expiration date and time
PATCH /rest/{IF}/token prolongs the expiration of the token
DELETE /rest/{IF}/token log off from API and cleaning up the session
Example
$ curl -X POST --user user:password https://demo.rscmdb.de/rest/sample/token/psk
{"token":"1s8edkoitj38j9l3lkvrv9fmn7","expires":"2024-10-26 19:44:18"}

$ curl -X GET https://demo.rscmdb.de/rest/sample/token --header "token: 1s8edkoitj38j9l3lkvrv9fmn7"
{"expires":"2024-10-26 19:44:18"}

Objects

The list of objects depends on the actual interface definition. Some of the objects may not be available in every implementation. Also the visibility of the objects depends on the user rights.

Object Drescription
address postal addresses for area object
area object to manage geographical area dependencies, anchor for physical staff (i.e. devices)
asnr documentation of AS-numbers
cabinet
device Management of devices and device names
devtype
dhcpoption object to manage DHCP optione depending to IP networks
dhcprange object to manage DHCP-ranges depending to IP networks
group Group management
ipaddr object to manage IP addresses (V4)
iparea object to manage IP container information, related to nearea objects
ipnet object to manage IP-Networks (V4)
ipservice
license Documentation and management of software licenses
natip object to manage NAT IP assignments (also accessible with ipnet object)
natpool object to manage IP networks containing NAT IP addresses
netarea object to manage logical network related structures, container for ipareas
realm object to manage realm information and dependencies
request Request handling
software Documentation and management of software (i.e. applications, operating systems)
tenant object to manage tenant information and dependencies
user User management
vlan Management of VLAN information and assignments
vlandomain Mangement of VLAN-Domains
vrf VRF management

asnr object

Method URL Notes
GET /rest/{IF}/asnr returns a list of all asnrs
GET /rest/{IF}/asnr/{id} returns information about a single asnr object
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST,PUT AS-Number, unique
owner text POST, PUT owner of the AS-number
notes string POST, PUT further notes or description
vrf_id int POST link to a VRF

<< zurück

cabinet object

Method URL Notes
GET /rest/{IF}/cabinet returns a list of all cabinets
GET /rest/{IF}/cabinet/{id} returns information about a single cabinet object
GET /rest/{IF}/cabinet/{id}/device information about connected devices (built in)
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST, PUT Cabinet name, unique
type string POST, PUT type of the cabinet
notes string POST, PUT further notes or description
height text POST height of the cabinet in HU
depth string POST depth of the cabinet in mm
area_id int POST link to the area (i.e. room)

<< zurück

device object

Method URL Notes
GET /rest/{IF}/device returns a list of all cabinets
GET /rest/{IF}/device/{id} returns information about a single cabinet object
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST, PUT Device name, unique (i.e. DNS name)
cabpos string POST, PUT built position in cabinet (HU)
height text POST height of the cabinet in HU
notes text POST, PUT further notes or description
type string POST, PUT global type of the device
area_id int POST, PUT link to the area (i.e. room)
cabinet_id int POST, PUT link to the cabinet
devtype_id int POST concrete device type
device_id int POST, PUT cluster and stack devices
realm_id int POST, PUT realm assigned
tenant_id int POST, PUT tenant of the device

<< zurück

devtype object

Method URL Notes
GET /rest/{IF}/devtype returns a list of all devtypes
GET /rest/{IF}/devtype/{id} returns information about a single devtype object
GET /rest/{IF}/devtype/{id}/device list of all devices of this devtype
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string PUT Device Type name, unique
notes text PUT further notes or description

<< zurück

dhcpoption object

Method URL Notes
GET /rest/{IF}/dhcpoption returns a list of all dhcpoption
GET /rest/{IF}/dhcpoption/{id} returns information about a single dhcpoption object
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST,PUT Option name, unique per ipnet
optid int POST Option ID, unique per ipnet
value string POST Option value
notes text POST,PUT further notes or description
ipnet_id int POST ipnet that contains this dhcp-option

<< zurück

dhcprange object

Method URL Notes
GET /rest/{IF}/dhcprange returns a list of all dhcpranges
GET /rest/{IF}/dhcprange/{id} returns information about a single dhcprange object
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
start IP POST,PUT start of the DHCP-Range
ende IP POST,PUT end of the DHCP range
leasetime string POST,PUT leasetime
notes text POST,PUT further notes or description
ipnet_id int POST ipnet that contains this dhcp-range

<< zurück

group object

Method URL Notes
GET /rest/{IF}/group returns a list of all groups
GET /rest/{IF}/group/{id} returns information about a single group object
GET /rest/{IF}/group/{id}/user information about assigned users
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST, PUT name of the group, unique
status string POST, PUT operational status
notes text POST, PUT further notes or description
startpage string POST, PUT startpage after logging in
defaultobj string POST, PUT default object

<< zurück

ipaddr object

Method URL Notes
GET /rest/{IF}/ipnet returns a list of all IP networks
GET /rest/{IF}/ipnet/{id} returns a list of all IP addresses in this IP network
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST,PUT name (DNS) assigned to ip address
addr IP POST, PUT IP address
natip int POST, PUT NAT IP address
natdir text POST, PUT NAT direction
gateway int POST, PUT default gateway flag
dhcp int POST, PUT dhcp flag
notes int POST, PUT further description
objstatus int POST, PUT Status of the IP address
ipif_id int POST, PUT link to interface
ipdevice_id int POST, PUT link to device

<< zurück

iparea object

Method URL Notes
GET /rest/{IF}/iparea returns a list of all iparea objects
GET /rest/{IF}/iparea/{id} information about a single iparea
GET /rest/{IF}/iparea/{id}/iparea returns a list of all ipareas below the iparea in the tree
GET /rest/{IF}/iparea/{id}/ipnet returns a list of all ipnets connected
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST,PUT iparea's name or readable identifier
net IP POST network address of iparea
bits int POST number of bits (CIDR), related to the iparea size
func int POST, PUT global flag
notes text POST, PUT further notes or description of the iparea

ipnet object

Method URL Notes
GET /rest/{IF}/ipnet returns a list of all IP networks
GET /rest/{IF}/ipnet/{id} information of the IP network
GET /rest/{IF}/ipnet/{id}/ipaddr returns a list of all IP addresses in this IP network
GET /rest/{IF}/ipnet/{id}/natip returns a list of all IP NAT addresses in this IP network
GET /rest/{IF}/ipnet/{id}/dhcpoption returns a list of the dhcp options of this network
GET /rest/{IF}/ipnet/{id}/dhcprange returns a list of the dhcp ranges of this network
GET /rest/{IF}/ipnet/{id}/service returns a list of all services that are related to this network
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST,PUT network's name or readable identifier
net IP POST network address
bits int POST number of bits (CIDR), related to the network size
notes text POST, PUT Description of the network
vrf_id int POST, PUT id of the related VRF
realm_id int POST, PUT id of the related realm
tenant_id int POST, PUT id of the related tenant

ipservice object

license object

natip object

natpool object

netarea object

Method URL Notes
GET /rest/{IF}/netarea returns a list of all netareas
GET /rest/{IF}/netarea/{id} Information about a single netarea
GET /rest/{IF}/netarea/{id}/netarea returns a list of all netareas below the selected in the tree
GET /rest/{IF}/netarea/{id}/iparea returns the assigned ipareas
GET /rest/{IF}/netarea/{id}/vlandomain returns the assigned vlandomains
GET /rest/{IF}/netarea/{id}/vlan returns a list of all vlans assigned to the netarea
GET /rest/{IF}/netarea/{id}/ipnet returns a list of all ipnets assigned to the netarea
available parameters
Parameter Type Method Notes
id int GET, PUT, DELETE unique identifier of the object
name string POST,PUT netarea's name, unique per hierarchy level
notes text POST, PUT Description
plancount int POST, PUT Number of planned users in the netarea
tcontact string POST, PUT name, UPN, etc. of the technical contact of this netarea
area_id int POST link to the geographical area
netarea_id int POST link to the predecessor in the netarea-hierarchy

realm object

request object

software object

tenant object

user object

vlan object

vlandomain object

vrf object