Groups API

TrueSight Network Automation REST API – Version 3.0 – Groups
The base URL for the API is:

https://serverName:portNumber/bca-networks/api

{{status colour="Blue" title="GET"/}}

/v3.0/groups

Click here to expand...

Description

Retrieves groups, matching any filter criteria; may filter by filterable group dynamic fields by including query parameters in the form 'filter.dynamicFieldName=value'

Parameters

Name	Located in	Description	Default	Schema
filter.name	query	Filter for groups matching this name, asterisk wildcards allowed		string
filter.realm	query	Filter for groups that belong to this realm		string
filter.autoGroup	query	Filter for auto-groups or non-auto-groups; when true, returns only auto-groups (including empty ones); when false, returns only non-auto-groups; when this filter is absent, no filtering is done		boolean Enum: [ "true", "false" ]
orderBy	query	Sort by the specified attribute (name, realm, or a listable group dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)	"+name"	string Enum: [ "+name", "-name", "+realm", "-realm" ]
offset	query	Return the specified page number	1	integer
limit	query	Define the number of rows in a page or the maximum number of groups to return	25	integer
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
200	successful operation	[ #GroupDTO ]
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to access groups
500	Internal server error: Unexpected exception occurred

{{status colour="Green" title="POST"/}}

/v3.0/groups

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
body	body	Complete attributes of the new group		#GroupDTO
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
201	Created: New group successfully added
400	Bad request: Input group DTO is missing or new group is invalid
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to add a new group
500	Internal server error: Unexpected exception occurred

{{status colour="Yellow" title="PUT"/}}

/v3.0/groups/{id}

Click here to expand...

Parameters

Name	Located in	Description	Schema
id	path	Database key of the group to be modified	string*
body	body	Complete new attribute values for the group; anything left out will be considered to be null and will be nulled out in the group; any required dynamic fields missing or null in the input will revert to default values; to change the realm a group belongs to, must first remove all devices from the group	#GroupDTO
Authorization	header	Authorization token formatted as 'Bearer [token]'	string*

Responses

Code	Description	Schema
200	successful operation	#GroupDTO
400	Bad request: Input group DTO is missing, modified group is invalid, or attempted to make an invalid type of change (such as renaming an auto-group); see error message for details
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to modify the group
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

{{status colour="Red" title="DELETE"/}}

/v3.0/groups/{id}

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
id	path	Database key of the group to be deleted		string*
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
200	successful operation	string
400	Bad request: group is currently in use or is a non-empty auto-group
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to delete the group
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

{{status colour="Yellow" title="PATCH"/}}

/v3.0/groups/{id}

Click here to expand...

Parameters

Name	Located in	Description	Schema
id	path	Database key of the group to be modified	string*
body	body	New attribute values for the group, in JSON Patch format	#JsonPatch
Authorization	header	Authorization token formatted as 'Bearer [token]'	string*

Responses

Code	Description	Schema
200	successful operation	#GroupDTO
400	Bad request: Input JSON patch information is missing, modified group is invalid, or attempted to make an invalid type of change (such as renaming an auto-group); see error message for details
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to modify the group
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

{{status colour="Blue" title="GET"/}}

/v3.0/groups/{id}/devices

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
id	path	Database key of the group of interest		string*
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
200	successful operation	[ #AbbreviatedDeviceDTO ]
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to access groups
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

{{status colour="Yellow" title="PUT"/}}

/v3.0/groups/{id}/devices/{deviceId}

Click here to expand...

Parameters

Name	Located in	Description	Schema
id	path	Database key of the group of interest	string*
deviceId	path	Database key of the device to be added to the group	string*
Authorization	header	Authorization token formatted as 'Bearer [token]'	string*

Responses

Code	Description	Schema
200	successful operation	string
400	Bad request: Device database key is not valid, device is not in the same realm as the group, or attempted to add a device to an auto-group
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to modify the group
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

{{status colour="Red" title="DELETE"/}}

/v3.0/groups/{id}/devices/{deviceId}

Click here to expand...

Parameters

Name	Located in	Description	Schema
id	path	Database key of the group of interest	string*
deviceId	path	Database key of the device to be removed from the group	string*
Authorization	header	Authorization token formatted as 'Bearer [token]'	string*

Responses

Code	Description	Schema
200	successful operation	string
400	Bad request: Device database key is not valid, device is not a member of the group, or attempted to remove a device from an auto-group
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to modify the group
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

{{status colour="Blue" title="GET"/}}

/v3.0/groups/{nameOrKey}

Click here to expand...

Parameters

Name	Located in	Description	Default	Schema
nameOrKey	path	Name or database key of the group of interest; a name must be unique across all realms for a group to be returned		string*
Authorization	header	Authorization token formatted as 'Bearer [token]'		string*

Responses

Code	Description	Schema
200	successful operation	#GroupDTO
401	Unauthorized: Failed to provide a suitable Authorization header or the specified user is not logged in
403	Forbidden: Not allowed to access groups
404	Not found: No single matching accessible group found
500	Internal server error: Unexpected exception occurred

Object Definitions

Object	Schema
AbbreviatedDeviceDTO	Click here to expand... { id: string The device's unique database key name: string The device's unique display name deviceDetailsLink: string Link to get complete details about this device realmId: string The database key of the realm this device belongs to realmName: string The name of the realm this device belongs to modelName: string The discovered model osImageName: string The discovered operating system version deviceTypeGuid: string The GUID of the device type deviceTypeName: string The name of the device type vendorGuid: string The GUID of the vendor vendorName: string The name of the vendor categoryId: integer The category categoryName: string The meaning of the numeric categoryId onlineFlag: boolean Whether or not this device is online discrepanciesFlag: boolean Whether or not this device has discrepancies violationsFlag: boolean Whether or not this device has compliance violations primaryInterfaceAddress: string The primary interface IP address, host name, or URL primaryInterfaceDeviceAgentId: string The database key of the primary interface device agent primaryInterfaceDeviceAgentName: string The name of the primary interface device agent primaryInterfaceDeviceAgentNIC: string The name of the primary interface device agent NIC primaryInterfaceAccessModeId: integer The primary interface access mode primaryInterfaceAccessModeName: string The meaning of the numeric primaryInterfaceAccessModeId primaryInterfaceTransferModeId: integer The primary interface transfer mode primaryInterfaceTransferModeName: string The meaning of the numeric primaryInterfaceTransferModeId primaryInterfaceDeviceSecurityProfileId: string The database key of the primary interface device security profile primaryInterfaceDeviceSecurityProfileName: string The name of the primary interface device security profile dynamicFields: [ The dynamic fields #DynamicFieldValueDTO ] }
DynamicFieldValueDTO	Click here to expand... { id: string The database key of the dynamic field whose value this is (read-only) name: string The name of the dynamic field (read-only) values: [ The value(s) for the dynamic field; for a single-value field, only the first entry is relevant; read-only for Auto Derived and Configuration Profiled types string ] dynamicFieldDetailsLink: string Link to get more detailed information about the dynamic field (read-only) }
GroupDTO	Click here to expand... { id: string The group's unique database key (read-only) name: string* The group's display name realmId: string* The database key of the realm this group belongs to realmDetailsLink: string Link to get complete details about the parent realm (read-only) autoGroupFlag: boolean Whether or not this group is an auto-group (read-only) dynamicFields: [ The dynamic fields #DynamicFieldValueDTO ] memberDevicesLink: string Link to get a list of the member devices (read-only) }
JsonPatch	Click here to expand... [ A list of JSON Patch operations #JsonPatch.OneOperation ]
JsonPatch.OneOperation	Click here to expand... Subclasses: #JsonPatch.Move #JsonPatch.Replace #JsonPatch.Remove #JsonPatch.Test #JsonPatch.Copy #JsonPatch.Add { }
JsonPatch.Pointer	Click here to expand... string Pointer or path to an element or property
JsonPatch.Add	Click here to expand... { op: string* Enum: [ "add" ] value: any* path: #JsonPatch.Pointer * }
JsonPatch.Remove	Click here to expand... { op: string* Enum: [ "remove" ] path: #JsonPatch.Pointer * }
JsonPatch.Replace	Click here to expand... { op: string* Enum: [ "replace" ] value: any* path: #JsonPatch.Pointer * }
JsonPatch.Move	Click here to expand... { op: string* Enum: [ "move" ] path: #JsonPatch.Pointer * from: #JsonPatch.Pointer * }
JsonPatch.Copy	Click here to expand... { op: string* Enum: [ "copy" ] path: #JsonPatch.Pointer * from: #JsonPatch.Pointer * }
JsonPatch.Test	Click here to expand... { op: string* Enum: [ "test" ] value: any* path: #JsonPatch.Pointer * }

Groups API

{{status colour="Blue" title="GET"/}} /v3.0/groups

Description

Parameters

Responses

{{status colour="Green" title="POST"/}} /v3.0/groups

Parameters

Responses

{{status colour="Yellow" title="PUT"/}} /v3.0/groups/{id}

Parameters

Responses

{{status colour="Red" title="DELETE"/}} /v3.0/groups/{id}

Parameters

Responses

{{status colour="Yellow" title="PATCH"/}} /v3.0/groups/{id}

Parameters

Responses

{{status colour="Blue" title="GET"/}} /v3.0/groups/{id}/devices

Parameters

Responses

{{status colour="Yellow" title="PUT"/}} /v3.0/groups/{id}/devices/{deviceId}

Parameters

Responses

{{status colour="Red" title="DELETE"/}} /v3.0/groups/{id}/devices/{deviceId}

Parameters

Responses

{{status colour="Blue" title="GET"/}} /v3.0/groups/{nameOrKey}

Parameters

Responses

Object Definitions

AbbreviatedDeviceDTO

DynamicFieldValueDTO

GroupDTO

JsonPatch

JsonPatch.OneOperation

JsonPatch.Pointer

JsonPatch.Add

JsonPatch.Remove

JsonPatch.Replace

JsonPatch.Move

JsonPatch.Copy

JsonPatch.Test

TrueSight Network Automation 23.4

On this page

{{status colour="Blue" title="GET"/}}

/v3.0/groups

{{status colour="Green" title="POST"/}}

/v3.0/groups

{{status colour="Yellow" title="PUT"/}}

/v3.0/groups/{id}

{{status colour="Red" title="DELETE"/}}

/v3.0/groups/{id}

{{status colour="Yellow" title="PATCH"/}}

/v3.0/groups/{id}

{{status colour="Blue" title="GET"/}}

/v3.0/groups/{id}/devices

{{status colour="Yellow" title="PUT"/}}

/v3.0/groups/{id}/devices/{deviceId}

{{status colour="Red" title="DELETE"/}}

/v3.0/groups/{id}/devices/{deviceId}

{{status colour="Blue" title="GET"/}}

/v3.0/groups/{nameOrKey}