Using the REST API

This chapter contains the following sections:

About the REST API

The Cisco ACI Multi-Site REST API is a programmatic interface that uses REST architecture. The API accepts and returns HTTP (not enabled by default) or HTTPS messages that contain JavaScript Object Notation (JSON) documents. You can use any programming language to generate the messages and the JSON documents that contain the API methods.

Standard REST methods are supported on the API, which includes POST, GET, PUT, and DELETE operations through HTTP. The PUT methods are idempotent, meaning that there is no additional effect if they are called more than once with the same input parameters. The GET method is nullipotent, meaning that it can be called zero or more times without making any changes (or that it is a read-only operation).

Payloads to and from the REST interface must be encapsulated through JSON encoding. Containment is defined by creating child attributes.

Object Naming

Resources are accessed by supplying the database identifier.

Composing REST API Requests

Read and Write Operations

/api/v1/tenants/<id>

v1 is the first version of the APIs.

Read Operations

After the object payloads are properly encoded as JSON, they can be used in create, read, update, or delete operations on the REST API.

Because the REST API is HTTP-based, defining the URI to access a certain resource type is important. The first two sections of the request URI simply define the protocol. Next in the request URI is the literal string /api, indicating that the API is invoked.

Write Operations

POST = create

PUT = update

If an object does not exist, it is created. If an object exists, it is updated to reflect any changes between its existing state and desired state.

Create and update operations use the same syntax as read operations. The create or update operation must target a specific entity. The payload of the POST and PUT operations contains JSON encoded data.

User Roles and Authorization

The API supports user-specific authorization based on the role of a user. A user can be associated with specific roles for access based on their function. While the admin can perform all operations, REST endpoints can be restricted based on a user's role. For more information, see the Cisco ACI Multi-Site Configuration Guide.

Search for Policies by displayName

GET
GET /api/v1/schemas/search-policies?type=:type&tenant-id=:tenantId&query=:query

Examples: 

 
/api/v1/schemas/search-policies?type=:type&tenant-id=:tenantId&query=:query
/api/v1/schemas/search-policies?type=vrf&tenant-id=T1&query=vrf
/api/v1/schemas/search-policies?type=contract&query=contra
/api/v1/schemas/search-policies?type=serviceGraph&tenant-id=T1&query=SG

Searchable Policy Types are as follows:

  • VRF

  • BD

  • Contract

  • Filter

  • serviceGraph

You must follow these guidelines when using searchable Policy Types:

  • TenantId is mandatory for the following policy types: VRF, BD, Filter, and serviceGraph.

  • TenantId is not required and is not used for Policy type Contracts.

  • Query must be three or more characters (in other cases, a BadRequest will be returned).

  • This API may return 100 records.

REQUEST


  <empty>

RESPONSE


{
  "policies": [
    {
      "vrfRef": "/schemas/58dad0988000004201faa03c/templates/template1/vrfs/UntitledVRF1",
      "policyName": "Untitled VRF 1",
      "schemaName": "Schema",
      "templateName": "Template 1"
    },
    {
      "vrfRef": "/schemas/58dae4b2800000e500b79f1c/templates/template1/vrfs/UntitledVRF1",
      "policyName": "Untitled VRF 1",
      "schemaName": "Schema2",
      "templateName": "Template 1"
    }
  ]
}