v4.0 Realms API


TrueSight Network Automation REST API – RealmService
The base URL for the API is:

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

realms

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

 /v4.0/realms
Click here to expand...


Description

Retrieves realms, matching any filter criteria, with the returned result being abbreviated or partially-detailed realms

Parameters

Name

Located in

Description

Default

Schema

query

Filter for realms matching this name, asterisk wildcards allowed


string

filter.action

query

Filter for realms where the user is allowed to perform this action, by action GUID


string

orderBy

query

Sort by the specified attribute (name, deviceCount, groupCount, or a listable realm dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+name"

string 
Enum: [
 "+name",
 "-name",
 "+deviceCount",
 "-deviceCount",
 "+groupCount",
 "-groupCount"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of realms to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access realms


500

Internal server error: Unexpected exception occurred


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

 /v4.0/realms
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new realm


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

201

Created: New realm successfully added


400

Bad request: Input realm DTO is missing or new realm is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to add a new realm


500

Internal server error: Unexpected exception occurred


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

 /v4.0/realms/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the realm of interest


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access realms


404

Not found: No single matching accessible realm found


500

Internal server error: Unexpected exception occurred


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

 /v4.0/realms/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the realm to be modified


string *

body

body

Complete new attribute values for the realm; anything left out will be considered to be null and will be nulled out in the realm; any required fallback or hardware inventory purge criteria or dynamic fields missing or null in the input will revert to default values


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input realm DTO is missing or modified realm is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to modify the realm


404

Not found: No single matching accessible realm found


500

Internal server error: Unexpected exception occurred


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

 /v4.0/realms/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the realm to be deleted


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: Realm is currently in use, or it is the only realm and cannot be deleted


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to delete the realm


404

Not found: No single matching accessible realm found


500

Internal server error: Unexpected exception occurred


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

 /v4.0/realms/{nameOrKey
}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the realm to be modified


string *

body

body

New attribute values for the realm, in JSON Patch format


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input JSON patch information is missing or modified realm is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to modify the realm


404

Not found: No single matching accessible realm found


500

Internal server error: Unexpected exception occurred


Object Definitions

Object

Schema

AbbreviatedRealmDTO


Click here to expand...


{ 
    id: string 
    The realm's unique database key 

     name: string 
    The realm's unique display name 

     canCopyFlag: boolean 
    Whether or not the user is allowed to copy this realm 

     canDeleteFlag: boolean 
    Whether or not the user is allowed to delete this realm 

     canEditFlag: boolean 
    Whether or not the user is allowed to edit this realm 

     deviceCount: integer 
    The number of devices currently in this realm 

     fallbackConfigsPurgeCriteria: PurgeCriteriaDTO
    Fallback purge criteria for device configurations (those configurations not covered by the per-trail or per-device-type purge criteria) 

     groupCount: integer 
    The number of groups currenlty in this realm, which includes static groups, auto-groups, and combo groups 

     hardwareInventoryPurgeCriteria: PurgeCriteriaDTO
    Purge criteria for device hardware inventory 

     purgeConfigsByDeviceTypes: { 
      Per-device-type device configuration purge criteria; this is a map where the key is a device type GUID string and the value is a PurgeCriteriaDTO 
    } 

     purgeConfigsByTrails: { 
      Per-trail device configuration purge criteria; this is a map where the key is a configuration trail GUID string and the value is a PurgeCriteriaDTO 
    } 

     purgeDevicesByDaysFlag: boolean 
    Whether or not to purge (automatically delete) devices that are flagged as offline 

     purgeDevicesDays: integer 
    Number of days a device can be offline before it is purged away (automatically deleted from the system) 

     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) 
}

JsonPatch


Click here to expand...


[ 
    A list of JSON Patch operations 

     JsonPatch.OneOperation
  ]

JsonPatch.OneOperation

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*
}

PurgeCriteriaDTO


Click here to expand...


{ 
    deviceAdapterName: string 
    The device type or configuration trail that this purge criteria applies to; (read-only) 

     purgeByCountFlag: boolean 
    Whether or not to purge by count 

     purgeCount: integer 
    The number of entities to be retained before the oldest are purged away 

     purgeByDaysFlag: boolean 
    Whether or not to purge by age 

     purgeDays: integer 
    The number of days an entity can age before it is purged away 
}

RealmDTO


Click here to expand...


{ 
    id: string 
    The realm's unique database key (read-only) 

     name: string * 
    The realm's unique display name 

     allowedActions: [ 
      The span actions the user is allowed to perform on this realm, containing the GUIDs of these actions (read-only) 

       string 
    ] 

     canCopyFlag: boolean 
    Whether or not the user is allowed to copy this realm (read-only) 

     canDeleteFlag: boolean 
    Whether or not the user is allowed to delete this realm (read-only) 

     canEditFlag: boolean 
    Whether or not the user is allowed to edit this realm (read-only) 

     fallbackConfigsPurgeCriteria: PurgeCriteriaDTO
    Fallback purge criteria for device configurations (those configurations not covered by the per-trail or per-device-type purge criteria) 

     hardwareInventoryPurgeCriteria: PurgeCriteriaDTO
    Purge criteria for device hardware inventory 

     purgeConfigsByDeviceTypes: { 
      Per-device-type device configuration purge criteria; this is a map where the key is a device type GUID string and the value is a PurgeCriteriaDTO 
    } 

     purgeConfigsByTrails: { 
      Per-trail device configuration purge criteria; this is a map where the key is a configuration trail GUID string and the value is a PurgeCriteriaDTO 
    } 

     purgeDevicesByDaysFlag: boolean 
    Whether or not to purge (automatically delete) devices that are flagged as offline 

     purgeDevicesDays: integer 
    Number of days a device can be offline before it is purged away (automatically deleted from the system) 

     dynamicFields: [ 
      The dynamic fields 

       DynamicFieldValueDTO
    ] 
}


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

TrueSight Network Automation 23.4