Skip to Content

Realms API

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

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


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

 /v3.0/realms
Click here to expand...
Parameters

Name

Located in

Description

Default

Schema

query

Filter for realms matching this name, asterisk wildcards allowed


string

orderBy

query

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

"+name"

string

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

[
   #RealmDTO
]

401

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


403

Forbidden: Not allowed to access realms


500

Internal server error: Unexpected exception occurred


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

 /v3.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 the specified user is not logged in


403

Forbidden: Not allowed to add a new realm


500

Internal server error: Unexpected exception occurred


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

 /v3.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 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 colour="Yellow" title="PUT"/}}

 /v3.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 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 colour="Red" title="DELETE"/}}

 /v3.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 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 colour="Yellow" title="PATCH"/}}

 /v3.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 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

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

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