REST API Overview
Cisco ACI Multi-Site REST API is a set of programming interfaces that uses Representational State Transfer (REST) architecture. The API contains
resources represented by Uniform Resource Identifiers (URIs), which allow to unambiguously identify each resource. Each URI
contains a protocol used to exchange the messages and the resource location string. For example, the https://<mso-ip>/api/v1/schemas URI specifies that the HTTPS protocol is to be used and the schemas resource path relative to the Cisco ACI Multi-Site Orchestrator address.
URIs can refer to a single object or a collection of objects. For example, http://<mso-ip>/api/v1/schemas represents all the schemas that exist in the fabric, whereas http://<mso-ip>/api/v1/schemas/{id} specifies a schema with a specific ID.
When you want to retrieve information or make changes to the fabric, you use API calls to exchange messages between your client and an URI. The messages must be in JavaScript Object Notation (JSON) format, but you can use any programming language to generate and send them.
The following standard REST methods are supported by the Cisco ACI Multi-Site REST API:
-
GET -
POST -
PUT -
DELETE -
PATCH
The PUT and PATCH methods are idempotent, which means 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, in other words it is
a read-only operation.
REST API Requests
The Cisco ACI Multi-Site REST API supports a number of standard API calls, which allow you to retrieve information about or make changes to your fabric. A typical REST API operation consists of three elements:
-
Request URL: The address of the resource to which you make the API call.
-
Request message: The JSON-formatted payload that contains the new data you want to add or update. For read-only operation (
GET) the request message is empty. -
Request response: The JSON-formatted response that contains the requested information.
The following sections provide an overview of each call as well as an example JSON payload.
GET Requests
The GET request is a read-only operation that allows you to retrieve information about one or more objects in the fabric. The following
example uses a GET request to obtain information about Cisco ACI Multi-Site Orchestrator users, such as their names, contact information, status, and privileges.
Request URL:
https://<mso-ip>/api/v1/usersRequest payload:
EMPTYRequest response:
{
"users": [{
"id": "5b6380972d0000f85ddea55e",
"username": "User01",
"password": "******",
"firstName": "fName01",
"lastName": "lName01",
"emailAddress": "User01@cisco.com",
"phoneNumber": "098-765-4321",
"accountStatus": "active",
"needsPasswordUpdate": true,
"roles": [{
"roleId": "0000ffff0000000000000031"
}, {
"roleId": "0000ffff0000000000000033"
}, {
"roleId": "0000ffff0000000000000035"
}
],
"domainId": "0000ffff0000000000000090"
}, {
"id": "5bb7aabc2c0000f34c7b89f7",
"username": "User02",
"password": "******",
"firstName": "fName02",
"lastName": "lName02",
"emailAddress": "User02@cisco.com",
"phoneNumber": "123-456-7890",
"accountStatus": "active",
"needsPasswordUpdate": true,
"roles": [{
"roleId": "0000ffff0000000000000031"
}, {
"roleId": "0000ffff0000000000000032"
}
],
"domainId": "0000ffff0000000000000090"
}
]
}POST and PUT Requests
The POST and PUT requests are write operations that allow you to create a new or update an existing object. Keep in mind, that if you are
updating an existing object, you must provide the object in its entirety. Any previously existing fields that are missing
from the POST payload, will be replaced by an empty string or null.
A PUT request is idempotent, which is the main difference between the PUT and POST requests.
The following example uses a POST request to create a new user. The request response contains the newly created object.
Request URL:
https://<mso-ip>/api/v1/usersRequest payload:
{
"id": "",
"username": "<username>",
"password": "<user-pass>",
"confirmPassword": "<user-pass>",
"firstName": "<user-first-name>",
"lastName": "<user-last-name>",
"emailAddress": "<user-email>",
"phoneNumber": "<user-phone>",
"accountStatus": "active",
"needsPasswordUpdate": true,
"roles": [{
"roleId": "0000ffff0000000000000031"
}
]
}
Request response:
{
"id": "5c40b8832b0000744a77ec1a",
"username": "<username>",
"password": "******",
"firstName": "<user-first-name>",
"lastName": "<user-last-name>",
"emailAddress": "<user-email>",
"phoneNumber": "<user-phone>",
"accountStatus": "active",
"needsPasswordUpdate": true,
"roles": [{
"roleId": "0000ffff0000000000000031"
}
],
"domainId": "0000ffff0000000000000090"
}
DELETE Requests
The DELETE request is a write operation that allows you to delete an existing object. A DELETE request does not require a payload and does not return a response.
The following example uses a DELETE request to delete the user we created in the POST example.
Request URL:
https://<mso-ip>/api/v1/users/5c40b8832b0000744a77ec1aRequest payload:
EMPTYRequest response:
EMPTYPATCH Requests
The PATCH request is a write operation that allow you to update an existing object. The main difference between PATCH and POST or PUT requests is that you can provide only the fields that contain new data rather than the entire object being updated. A PATCH
request is neither safe nor idempotent, because a PATCH operation cannot ensure the entire resource has been updated. Also,
unlike other API requests, a PATCH request contains instructions on how to modify a resource, rather than a version of the
resource itself.
 Note |
The current release of Cisco ACI Multi-Site Orchestrator supports |
When creating PATCH requests, the payload must contain the following:
-
op: the operation to be performed by the request. Currently supported operations areadd,remove, orreplace. -
path: the path to the resource that you are updating. The value contains the URI of the resource and the position inside that resource where the information will be added.For
addoperations, the position value can be any positive integer or a dash (-) to specify the end of the schema. For example,/templates/<template-name>/vrfs/-would indicate adding a new VRF at the end of the current list, whereas/templates/<template-name>/vrfs/2would add the VRF at the second position.For
replaceoperations, the position value can also be a the name of the object to replace in addition to the index. For example,/templates/<template-name>/anps/AP1would replace the application profile namedAP1 -
value: the new or updated value or object. For example,{"vrfname" : "vrf1"}would specify a new VRF with the name vrf1.You do not need to provide the
valuefield forremoveoperations.
PATCH API has the following limitations:
-
You cannot use the PATCH API to change a template name, because multiple references in the fabric must be updated. Use PUT request instead.
Names should not contain the slash (
/) character. If the name contains a slash, you cannot use it to access an element in an array and must use the element's index instead.Names must not contain numbers only. This limitation is caused by the fact that pure numbers are interpreted as the PATCH index.
For site local schema objects, refer to the Site ID and Template name combination as
<site-id>-<template-name>, for example/sites/5b7d29c2a7fa00a7fae9bbf3-SampleTemplate/epgs
The following two example illustrate how to uses the PATCH requests to add and remove a VRF in a template in an existing schema. The request response contains the entire object that
was updated.
Add an Object Using PATCH Request
The following example uses a PATCH request to add a VRF to a template in an existing schema. The request response contains the entire object that was updated.
Original schema:
{
"id": "5c4b55db1a00003422f2215e",
"displayName": "SampleSchema",
"templates": [
{
"name": "Template1",
"displayName": "Template1",
"tenantId": "0000ffff0000000000000010",
"anps": [],
"vrfs": [],
"bds": [],
"contracts": [],
"filters": [],
"externalEpgs": [],
"serviceGraphs": [],
"intersiteL3outs": []
}
]
}Request URL:
https://<mso-ip>//api/v1/schemas/5c4b55db1a00003422f2215eRequest payload:
[{
"op": "add",
"path": "/templates/Template1/vrfs/-",
"value": {
"displayName" : "vrf1",
"name" : "vrf1" }
}]Request response:
{
"id": "5c4b55db1a00003422f2215e",
"displayName": "SampleSchema",
"templates": [
{
"name": "Template1",
"displayName": "T1",
"tenantId": "0000ffff0000000000000010",
"anps": [],
"vrfs": [
{
"name": "vrf1",
"displayName": "vrf1",
"vrfRef": "/schemas/5c4b55db1a00003422f2215e/templates/Template1/vrfs/vrf1",
"vzAnyProviderContracts": [],
"vzAnyConsumerContracts": []
}
],
"bds": [],
"contracts": [],
"filters": [],
"externalEpgs": [],
"serviceGraphs": [],
"intersiteL3outs": []
}
]
}Remove an Object Using PATCH Request
The following example uses a PATCH request to remove a VRF from a template in an existing schema. The request response contains the entire object that was updated.
Original schema:
{
"id": "5c4b55db1a00003422f2215e",
"displayName": "SampleSchema",
"templates": [
{
"name": "Template1",
"displayName": "T1",
"tenantId": "0000ffff0000000000000010",
"anps": [],
"vrfs": [
{
"name": "vrf1",
"displayName": "vrf1",
"vrfRef": "/schemas/5c4b55db1a00003422f2215e/templates/Template1/vrfs/vrf1",
"vzAnyProviderContracts": [],
"vzAnyConsumerContracts": []
}
],
"bds": [],
"contracts": [],
"filters": [],
"externalEpgs": [],
"serviceGraphs": [],
"intersiteL3outs": []
}
]
}Request URL:
https://<mso-ip>//api/v1/schemas/5c4b55db1a00003422f2215eRequest payload:
[{
"op": "remove",
"path": "/templates/Template1/vrfs/vrf1"
}]Request response:
{
"id": "5c4b55db1a00003422f2215e",
"displayName": "SampleSchema",
"templates": [
{
"name": "Template1",
"displayName": "T1",
"tenantId": "0000ffff0000000000000010",
"anps": [],
"vrfs": [],
"bds": [],
"contracts": [],
"filters": [],
"externalEpgs": [],
"serviceGraphs": [],
"intersiteL3outs": []
}
]
}REST API User Roles and Authorization
The Cisco ACI Multi-Site Orchestrator API supports multiple users, each with their own user-specific authorization and set of privileges based on
their role. A user can be associated with specific roles for access based on their function and REST endpoints can be restricted
based on the user's role. The admin user has unrestricted access. For more information on creating and manager users and their roles, see the Cisco ACI Multi-Site Configuration Guide.
Feedback