Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

API Endpoints and Parameters

This topic lists the supported API endpoints, parameters, and the REST API HTTP Response Codes for accessing Data Center Assurance using external APIs.

Supported API Endpoints

DC Assurance supports API requests for the following resources:

  • Sites
  • Systems
  • Links
  • Interfaces

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 DC Assurance for each resource type.

Table 1: Supported API 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

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.

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

Table 2: Supported Parameters
Parameter Value Description Example

Field

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 3: 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

Array contains specified scalar value

filter=interface_members contains 'ge-0/0/1'

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

Table 4: 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')

REST API HTTP Response Codes

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

Table 5: HTTP Response Codes
Status Description
200

OK.

The DC 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 towards the DC 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.