API Endpoints and Parameters

Supported API Endpoints

Data Center Assurance supports API requests for the following resources:

Sites
Systems
Links
Interfaces
Pods
Racks
Tags

There are two types of API endpoints built for each resource type:

Collection Retrieval endpoints–used to access groups of related resources. For example, GET /api/v1/datacenter/orgs/<org-id>/inventory/systems
Instance Retrieval endpoints–used to access a single, specific resource identified by a unique ID. For example, GET /api/v1/datacenter/orgs/<org-id>/inventory/systems/<system-id>

Table 1 lists the API endpoints supported on Data Center Assurance to retrieve inventory information for each resource type.

Table 2 lists the API endpoints supported on Data Center Assurance to retrieve observability information from the data center network.

Table 3 lists the API endpoints supported on Data Center Assurance to execute certain operations in the data center network.

Table 1: Supported Inventory Endpoints
Resource Type	API Endpoints
Sites	`GET /api/v1/datacenter/orgs/<org-id>/inventory/sites` `GET /api/v1/datacenter/orgs/<org-id>/inventory/sites/<site-id>`
Systems	`GET /api/v1/datacenter/orgs/<org-id>/inventory/systems` `GET /api/v1/datacenter/orgs/<org-id>/inventory/systems/<system-id>`
Links	`GET /api/v1/datacenter/orgs/<org-id>/inventory/links` `GET /api/v1/datacenter/orgs/<org-id>/inventory/links/<link-id>`
Interfaces	`GET /api/v1/datacenter/orgs/<org-id>/inventory/interfaces` `GET /api/v1/datacenter/orgs/<org-id>/inventory/interfaces/<interface-id>` `GET /api/v1/datacenter/orgs/<org-id>/inventory/systems/<system-id>/interfaces`
Pods	`GET /api/v1/datacenter/orgs/<org-id>/inventory/pods` `GET /api/v1/datacenter/orgs/<org-id>/inventory/pods/<pod-id>`
Racks	`GET /api/v1/datacenter/orgs/<org-id>/inventory/racks` `GET /api/v1/datacenter/orgs/<org-id>/inventory/racks/<rack-id>`
Tags	`GET /api/v1/datacenter/orgs/<org-id>/inventory/tags` `GET /api/v1/datacenter/orgs/<org-id>/inventory/sites/<site-id>/tags` `GET /api/v1/datacenter/orgs/<org-id>/inventory/tags/<tag-id>`

Table 2: Supported Observability Endpoints
Type	Description	API Endpoints
Anomalies	Retrieves information about the anomalies raised in the network, and the list of impacted services or clients for specified anomalies.	`GET /api/v1/datacenter/orgs/<org-id>/observability/anomalies` `GET /api/v1/datacenter/orgs/<org-id>/observability/anomalies/<anomaly-id>` `GET /api/v1/datacenter/orgs/<org-id>/observability/anomalies/<anomaly-id>/impacted-services` `GET /api/v1/datacenter/orgs/<org-id>/observability/anomalies/<anomaly-id>/impacted-clients`

Table 3: Supported Operations Endpoints
Operation	Description	API Endpoints
MAC Address Lookup Query	Locates a MAC address within a particular site.	`GET /api/v1/datacenter/orgs/<org-id>/operations/sites/<site-id>/query-mac` See MAC Address Lookup Query for more details.
Run System Command	Executes a command on a system and creates a one-time retrievable resource with the results.	`POST /api/v1/datacenter/orgs/<org-id>/operations/sites/<site-id>/systems/<system-id>/run-command` `GET /api/v1/datacenter/orgs/<org-id>/operations/sites/<site-id>/systems/<system-id>/run-command/request-id` Note: You must have administrator privileges to execute the run command API endpoints. See Run System Command for more details.

MAC Address Lookup Query
Run System Command

MAC Address Lookup Query

Table 4 lists the parameters supported by the API endpoints for MAC address lookup query.

Table 4: Parameters for MAC Address Lookup Query
Parameter	Description
`mac_address`	The full or partial MAC address that you want to search for. Repeat this parameter to query multiple MAC addresses.
`system_id`	The UUID of a system where you want to search for the MAC addresses.
`vlan`	The ID of a VLAN where you want to search for the MAC addresses. Repeat this parameter to specify multiple VLAN IDs.
`vxlan`	The VXLAN Network Identifier (VNI) of a VXLAN where you want to search for the MAC addresses. Repeat this parameter to specify multiple VXLAN VNIs.
`limit`	The maximum number of items to return in the response. Default value is 100.
`offset`	The number of items to skip before starting to return results. Default value is 0.

Run System Command

To execute a command on a system, you must use the two run command API endpoints in combination:

A POST request to run a CLI command on the specified system:

POST /api/v1/datacenter/orgs/<org-id>/operations/sites/<site-id>/systems/<system-id>/run-command
A GET request to retrieve the result and output of the executed command:

GET /api/v1/datacenter/orgs/<org-id>/operations/sites/<site-id>/systems/<system-id>/run-command/request-id

The POST request to run the command must include the following fields:

Table 5: POST Request Input Fields
Field	Description
`command_text`	The CLI command to be executed.
`output_format`	The format of the CLI command output. The possible values are: “OUTPUT_FORMAT_TEXT” “OUTPUT_FORMAT_JSON” “OUTPUT_FORMAT_XML”

Executing this POST request returns a request ID assigned to the CLI command.

After you execute the POST request, run the GET request using the returned request ID to retrieve the result and output of the executed command in the format that you specified.

Note:

The POST endpoint can be invoked only once. Upon retrieval, the command result will be automatically removed.

Supported Parameters

You can add parameters to modify the output of your API request as per your requirements.

The table below describes the supported parameters and their functions, along with their values and examples.

Table 6: Supported Parameters
Parameter	Value	Description	Example
`fields`	Field name(s)	Enter a comma-separated list of additional field names to include in the response.	`GET /api/v1/datacenter/orgs/<org-id>/inventory/systems?fields=deploy_mode, management_ip`
`expand`	Reference name(s)	Enter a reference name to view the name field for that reference.	`GET /api/v1/datacenter/orgs/<org-id>/inventory/systems?expand=site`
`filter`	Filter conditions	Select a subset of resources based on field values, logical conditions, and grouping.	See the Supported Operators for Filtering section below for more information.
`sort`	Field name	Sort by the specified field, either in ascending or descending order.	Sort in ascending order: `GET /api/v1/datacenter/orgs/<org-id>/inventory/systems?sort=name` Sort in descending order: `GET /api/v1/datacenter/orgs/<org-id>/inventory/systems?sort=-name`
`limit`	Number	Maximum number of items to return in the response. Default value is 100.	`GET /api/v1/datacenter/orgs/<org-id>/inventory/systems?limit=100`
`offset`	Number	Number of items to skip before starting to return results. Default value is 0.	`GET /api/v1/datacenter/orgs/<org-id>/inventory/systems?offset=2`

Supported Operators for Filtering

The following table lists the comparison operators supported for the filter parameter.

Table 7: Comparison Operators
Operator	Description	Example
`eq`	Equals	`filter=role eq 'SYSTEM_ROLE_SPINE'`
`ne`	Not equals	`filter=role ne 'SYSTEM_ROLE_GENERIC_SYSTEM'`
`gt`	Greater than	`filter=speed gt 10000`
`ge`	Greater or equal	`filter=speed ge 10000`
`lt`	Less than	`filter=speed lt 10000`
`le`	Less or equal	`filter=speed le 10000`
`contains`	For an array or reference collection, checks for an exact scalar value. For a scalar string field, performs a case-insensitive substring match.	`filter=interface_members contains 'ge-0/0/1'` `filter=hostname contains 'leaf'`

The following table lists the logical operators supported for the filter parameter.

Table 8: Logical Operators
Operator	Description	Example
`and`	Logical AND	`filter=role eq 'SYSTEM_ROLE_SPINE' and vendor eq 'Juniper'`
`or`	Logical OR	`filter=role eq 'SYSTEM_ROLE_SPINE' or role eq 'SYSTEM_ROLE_LEAF'`
`not`	Logical NOT	`filter=not (role eq 'SYSTEM_ROLE_SPINE')`

Output Fields of Endpoint Requests

Each resource type defines its fields in two categories:

Core fields–represent the minimal, commonly required attributes of a resource.
Additional fields–represent less commonly used or optional attributes that require more processing power.

The output for a collection retrieval endpoint returns only the core fields by default. To include additional fields in the output, use the fields query parameter.

The output for an instance retrieval endpoint displays both core and additional fields by default.

REST API HTTP Response Codes

After you run the API request on Data Center Assurance, it returns an output along with one of the following HTTP response codes.

Table 9: HTTP Response Codes
Status	Description
`200`	OK. The Data Center Assurance API understood the call and answered it without errors.
`400`	Bad Request. The API endpoint exists but its syntax/payload is incorrect.
`401`	Unauthorized. The authentication toward the Data Center Assurance API failed. You could receive this code if your token is wrong, or if your token was not sent to the API with the proper format. Validate your authentication information.
`404`	Not found. The API endpoint doesn’t exist, or the resource doesn’t exist.

ON THIS PAGE