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.

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.

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.

The Multi-Site Orchestrator GUI will ensure that any concurrent updates on the same site or schema object cannot unintentionally overwrite each other. If you attempt to make changes to a site or schema that was updated by another user since you opened it, the GUI will reject any subsequent changes you try to make and present a warning requesting you to refresh the object before making additional changes:

However, the default REST API functionality was left unchanged in order to preserve backward compatibility with existing applications. In other words, while the UI is always enabled for this protection, you must explicitly enable it for your API calls for MSO to keep track of configuration changes.

Note

When enabling this feature, note the following: This release supports detection of conflicting configuration changes for Site and Schema objects only. Only PUT and PATCH API calls support the version check feature. If you do not explicitly enable the version check parameter in your API calls, MSO will not track any updates internally. And as a result, any configuration updates can be potentially overwritten by both subsequent API calls or GUI users.

To enable the configuration version check, you can pass the enableVersionCheck=true parameter to the API call by appending it to the end of the API endpoint you are using, for example:

https://<mso-ip-address>/mso/api/v1/schemas/<schema-id>?enableVersionCheck=true

Example

We will use a simple example of updating the display name of a template in a schema to show how to use the version check attribute with PUT or PATCH calls.

First, you would GET the schema you want to modify, which will return the current latest version of the schema in the call's response:

{
    "id": "601acfed38000070a4ee9ec0",
    "displayName": "Schema1",
    "description": "",
    "templates": [
        {
            "name": "Template1",
            "displayName": "current name",
            [...]
        }
    ],
    "_updateVersion": 12,
    "sites": [...]
}

Then you can modify the schema in one of two ways appending enableVersionCheck=true to the request URL:

Note	You must ensure that the value of the "_updateVersion" field in the payload is the same as the value you got in the original schema.

• Using the PUT API with the entire updated schema as payload:

  PUT /v1/schemas/601acfed38000070a4ee9ec0?enableVersionCheck=true

  {
      "id": "601acfed38000070a4ee9ec0",
      "displayName": "Schema1",
      "description": "",
      "templates": [
          {
              "name": "Template1",
              "displayName": "new name",
              [...]
          }
      ],
      "_updateVersion": 12,
      "sites": [...]
  }

• Using any of the PATCH API operations to make a specific change to one of the objects in the schema:

  PATCH /v1/schemas/601acfed38000070a4ee9ec0?enableVersionCheck=true

  [ 
      {
          "op": "replace", 
          "path": "/templates/Template1/displayName", 
          "value": "new name",
          "_updateVersion": 12
      }
  ]

When the request is made, the API will increment the current schema version by 1 (from 12 to 13) and attempt to create the new version of the schema. If the new version does not yet exist, the operation will succeed and the schema will be updated; if another API call (with enableVersionCheck enabled) or the UI have modified the schema in the meantime, the operation fails and the API call will return the following response:

{
    "code": 400,
    "message": "Update failed, object version in the DB has changed, refresh your client and retry"
}

Cisco ACI Multi-Site Orchestrator uses OpenAPI (also known as Swagger) to provide a complete API reference for developers linked directly from the Orchestrator's GUI. OpenAPI allows you to visualize and interact with the API's resources. The direct connection from the reference document to the live Orchestrator API provides an easy way to write and test simple request directly from the OpenAPI reference UI.

• APIC Information API: Allows you to query the Cisco APIC sites directly for specific information, such as Pods, Tenants, VMM domains, L3Outs, and so on. This API is part of the site API.

• Audit API: Allows you to access Cisco ACI Multi-Site Orchestrator's audit logs and query for information, such as records and users, as well as download all or specific records.

• Backup API: Allows you to create, update, delete, or restore a backup of Cisco ACI Multi-Site Orchestrator configuration, as well as schedule a backup.

• Deployment API: Allows you to deploy the Schemas and Templates directly to sites using SiteId and TemplateName.

• Fabric Connectivity API: Allows you to query for fabric connectivity, connectivity status, multipod information, and so on. This API is part of the site API.

• Infrastructure Logs API: Allows you to query for infrastructure and platform logs. This API is part of the platform API.

• Platform API: Allows you to query for information about platform nodes and labels.

• Policy Report API: Allows you to query for policy deployment reports. This API is part of the platform API.

• Schema API: Allows you to create, update, patch, or delete schemas, as well as query for information associated with a schema.

• Site API: Allows you to create, update, patch, or delete sites. This API is part of the site API.

• Tenant API: Allows you to create, update, patch, or delete tenants, as well as query for information associated with a tenant. This API is part of the schema API.

• User API: Allows you to create, update, or delete users, update user roles, and configure authentication providers, such as LDAP, TACACs, or RADIUS.

This section illustrates some simple examples of using browser tools to view, modify, and re-send REST API calls. The examples presented here use Google Chrome, however the steps are similar for other browsers. Accessing each browser's developer tools is described in Using In-Browser DevTools to View REST API Calls.

When you perform an action in the Cisco ACI Multi-Site Orchestrator GUI with DevTools open, you can see a list of the API calls made by the GUI to the Orchestrator. From there on, you can select each individual call to inspect its request and response contents.

For example, if you click on the Schemas view in the left-hand navigation sidebar of the GUI, two calls are made to /api/v1/schemas – one to get a list of schemas and another to get a list of tenants for each schema:

If you then select one of the calls, for example tenants, you can view the call details, such as the request method, request URL, authentication token, and so on. The response tab provides the exact XML string received in response to the call.

If you right-click on any of the listed API calls, you can choose to copy the call in any of the available formats:

For example, you can choose to copy the request as cURL, which you can then execute in 3rd party scripts:

curl "https://172.31.187.59/api/v1/schemas/tenants" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1Mzg3NjkyNjcsImlhdCI6MTUzODc2ODA2NywiaXNzIjoiNDRiMGNlZjI1MTgzNDE3YTk5MDJhODg1MmFhNzhhZmUiLCJ1c2VySWQiOiIwMDAwZmZmZjAwMDAwMDAwMDAwMDAwMjAiLCJ1c2VybmFtZSI6ImFkbWluIiwicGVybWlzc2lvbnMiOlsidmlldy1zaXRlcyIsIm1hbmFnZS1zaXRlcyIsInZpZXctdGVuYW50cyIsIm1hbmFnZS10ZW5hbnRzIiwidmlldy10ZW5hbnQtc2NoZW1hcyIsIm1hbmFnZS10ZW5hbnQtc2NoZW1hcyIsInZpZXctc2NoZW1hcyIsIm1hbmFnZS1zY2hlbWFzIiwidmlldy11c2VycyIsIm1hbmFnZS11c2VycyIsInZpZXctcm9sZXMiLCJtYW5hZ2Utcm9sZXMiLCJ2aWV3LWxhYmVscyIsIm1hbmFnZS1sYWJlbHMiLCJwbGF0Zm9ybS1sb2dzIiwiYmFja3VwLWRiIiwidmlldy1hbGwtYXVkaXQtcmVjb3JkcyIsIm1hbmFnZS1hdWRpdC1yZWNvcmRzIl19.BDVrkImuIaX57aG0gfWUsXE5NVJPq2FGKP289XCjHRw" -H "DNT: 1" -H "Accept-Encoding: gzip, deflate, br" -H "Accept-Language: en-US,en;q=0.9" -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36" -H "Content-Type: application/json" -H "Accept: application/json" -H "Referer: https://172.31.187.59/schemas" -H "Connection: keep-alive" --compressed --insecure

Another example would be the users API which is called when you select the Users view. The GUI retrieves the list of users using the following corresponding cURL request:

curl "https://172.31.187.59/api/v1/users" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1Mzg3Njk1NzAsImlhdCI6MTUzODc2ODM3MCwiaXNzIjoiMThhNWM3MWNiNmM1NGMwNmFjNDIzYTI5ZWNiNWI5NzAiLCJ1c2VySWQiOiIwMDAwZmZmZjAwMDAwMDAwMDAwMDAwMjAiLCJ1c2VybmFtZSI6ImFkbWluIiwicGVybWlzc2lvbnMiOlsidmlldy1zaXRlcyIsIm1hbmFnZS1zaXRlcyIsInZpZXctdGVuYW50cyIsIm1hbmFnZS10ZW5hbnRzIiwidmlldy10ZW5hbnQtc2NoZW1hcyIsIm1hbmFnZS10ZW5hbnQtc2NoZW1hcyIsInZpZXctc2NoZW1hcyIsIm1hbmFnZS1zY2hlbWFzIiwidmlldy11c2VycyIsIm1hbmFnZS11c2VycyIsInZpZXctcm9sZXMiLCJtYW5hZ2Utcm9sZXMiLCJ2aWV3LWxhYmVscyIsIm1hbmFnZS1sYWJlbHMiLCJwbGF0Zm9ybS1sb2dzIiwiYmFja3VwLWRiIiwidmlldy1hbGwtYXVkaXQtcmVjb3JkcyIsIm1hbmFnZS1hdWRpdC1yZWNvcmRzIl19.CNs-nM3V73CBcYRBHqgfwtx3tAW5a9wsnMHqkKDGjDE" -H "DNT: 1" -H "Accept-Encoding: gzip, deflate, br" -H "Accept-Language: en-US,en;q=0.9" -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36" -H "Content-Type: application/json" -H "Accept: application/json" -H "Referer: https://172.31.187.59/users" -H "Connection: keep-alive" --compressed --insecure

And the request returns a JSON-formatted XML message similar to the following:

{
    "users": [{
            "id": "59f17fe7120000da00bf0d11",
            "username": "max-usermgr",
            "password": "******",
            "firstName": "firstName",
            "lastName": "lastName",
            "emailAddress": "email@domain.com",
            "phoneNumber": "7474747477",
            "accountStatus": "active",
            "needsPasswordUpdate": false,
            "roles": [{
                    "roleId": "0000ffff0000000000000035"
                }
            ],
            "domainId": "0000ffff0000000000000090"
        }, {
            "id": "59f17f9e0e00001701000326",
            "username": "max-schemamgr",
            "password": "******",
            "firstName": "firstName",
            "lastName": "lastName",
            "emailAddress": "email@domain.com",
            "phoneNumber": "34343442234",
            "accountStatus": "active",
            "needsPasswordUpdate": false,
            "roles": [{
                    "roleId": "0000ffff0000000000000033"
                }
            ],
            "domainId": "0000ffff0000000000000090"
        }, {
            "id": "59f17f6b120000eb00bf0d10",
            "username": "max-sitemgr",
            "password": "******",
            "firstName": "firstName",
            "lastName": "lastName",
            "emailAddress": "email@domain.com",
            "phoneNumber": "3838833838",
            "accountStatus": "active",
            "needsPasswordUpdate": false,
            "roles": [{
                    "roleId": "0000ffff0000000000000032"
                }
            ],
            "domainId": "0000ffff0000000000000090"
        }
    ]
}

curl "https://172.31.187.59/api/v1/users" -H "Origin: https://172.31.187.59" -H "Accept-Encoding: gzip, deflate, br" -H "Accept-Language: en-US,en;q=0.9" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1Mzg3Njk1NzAsImlhdCI6MTUzODc2ODM3MCwiaXNzIjoiMThhNWM3MWNiNmM1NGMwNmFjNDIzYTI5ZWNiNWI5NzAiLCJ1c2VySWQiOiIwMDAwZmZmZjAwMDAwMDAwMDAwMDAwMjAiLCJ1c2VybmFtZSI6ImFkbWluIiwicGVybWlzc2lvbnMiOlsidmlldy1zaXRlcyIsIm1hbmFnZS1zaXRlcyIsInZpZXctdGVuYW50cyIsIm1hbmFnZS10ZW5hbnRzIiwidmlldy10ZW5hbnQtc2NoZW1hcyIsIm1hbmFnZS10ZW5hbnQtc2NoZW1hcyIsInZpZXctc2NoZW1hcyIsIm1hbmFnZS1zY2hlbWFzIiwidmlldy11c2VycyIsIm1hbmFnZS11c2VycyIsInZpZXctcm9sZXMiLCJtYW5hZ2Utcm9sZXMiLCJ2aWV3LWxhYmVscyIsIm1hbmFnZS1sYWJlbHMiLCJwbGF0Zm9ybS1sb2dzIiwiYmFja3VwLWRiIiwidmlldy1hbGwtYXVkaXQtcmVjb3JkcyIsIm1hbmFnZS1hdWRpdC1yZWNvcmRzIl19.CNs-nM3V73CBcYRBHqgfwtx3tAW5a9wsnMHqkKDGjDE" -H "Content-Type: application/json" -H "Accept: application/json" -H "Referer: https://172.31.187.59/users/create" -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36" -H "Connection: keep-alive" -H "DNT: 1" --data-binary "^{^\^"lastName^\^":^\^"lastName^\^",^\^"needsPasswordUpdate^\^":true,^\^"username^\^":^\^"newUserName^\^",^\^"phoneNumber^\^":^\^"1234567890^\^",^\^"emailAddress^\^":^\^"email^@domain.com^\^",^\^"id^\^":^\^"^\^",^\^"firstName^\^":^\^"firstName^\^",^\^"confirmPassword^\^":^\^"passw0rd^#^\^",^\^"password^\^":^\^"passw0rd^#^\^",^\^"accountStatus^\^":^\^"active^\^",^\^"roles^\^":^[^{^\^"roleId^\^":^\^"0000ffff0000000000000031^\^"^},^{^\^"roleId^\^":^\^"0000ffff0000000000000032^\^"^}^]^}" --compressed --insecure

{
    "id": "5bb7be240f00008206d3f137",
    "username": "newUserName",
    "password": "******",
    "firstName": "firstName",
    "lastName": "lastName",
    "emailAddress": "email@domain.com",
    "phoneNumber": "1234567890",
    "accountStatus": "active",
    "needsPasswordUpdate": true,
    "roles": [{
            "roleId": "0000ffff0000000000000031"
        }, {
            "roleId": "0000ffff0000000000000032"
        }
    ],
    "domainId": "0000ffff0000000000000090"
}