Using the REST API

[Pages:22]Using the REST API

This chapter contains the following sections: ? REST API Overview, on page 1 ? REST API User Roles and Authorization, on page 2 ? REST API Requests, on page 2 ? Concurrent Configuration Updates, on page 12 ? REST API Reference (OpenAPI/Swagger), on page 14 ? Using In-Browser DevTools to View REST API Calls, on page 18 ? Using In-Browser DevTools to Work with REST API Calls, on page 19

REST API Overview

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 URI specifies that the HTTPS protocol is to be used and the schemas resource path relative to the Multi-Site Orchestrator address. URIs can refer to a single object or a collection of objects. For example, represents all the schemas that exist in the fabric, whereas {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 Multi-Site REST API:

? GET ? POST ? PUT ? DELETE ? PATCH

Using the REST API 1

REST API User Roles and Authorization

Using the REST API

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 User Roles and Authorization

The 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 Multi-Site Configuration Guide.

REST API Requests

The 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 Multi-Site Orchestrator users, such as their names, contact information, status, and privileges. Request URL:



Request payload:

EMPTY

Request response:

{ "users": [{ "id": "5b6380972d0000f85ddea55e", "username": "User01", "password": "******", "firstName": "fName01", "lastName": "lName01", "emailAddress": "User01@", "phoneNumber": "098-765-4321", "accountStatus": "active", "needsPasswordUpdate": true, "roles": [{ "roleId": "0000ffff0000000000000031" }, {

Using the REST API 2

Using the REST API

POST and PUT Requests

"roleId": "0000ffff0000000000000033" }, {

"roleId": "0000ffff0000000000000035" } ], "domainId": "0000ffff0000000000000090" }, { "id": "5bb7aabc2c0000f34c7b89f7", "username": "User02", "password": "******", "firstName": "fName02", "lastName": "lName02", "emailAddress": "User02@", "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:



Request payload:

{ "id": "", "username": "", "password": "", "confirmPassword": "", "firstName": "", "lastName": "", "emailAddress": "", "phoneNumber": "", "accountStatus": "active", "needsPasswordUpdate": true, "roles": [{ "roleId": "0000ffff0000000000000031" } ]

}

Request response:

Using the REST API 3

DELETE Requests

Using the REST API

{ "id": "5c40b8832b0000744a77ec1a", "username": "", "password": "******", "firstName": "", "lastName": "", "emailAddress": "", "phoneNumber": "", "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:



Request payload:

EMPTY

Request response:

EMPTY

PATCH 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 Multi-Site Orchestrator supports PATCH requests only for some objects. Check the Swagger API reference to see if an object supports PATCH requests.

When creating PATCH requests, the payload must contain the following:

? op: the operation to be performed by the request. Currently supported operations are add, remove, or replace.

? 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 add operations, the position value can be any positive integer or a dash (-) to specify the end of the schema. For example, /templates//vrfs/- would indicate adding a new VRF at the

Using the REST API 4

Using the REST API

PATCH Requests

end of the current list, whereas /templates//vrfs/2 would add the VRF at the second position.

For replace operations, the position value can also be a the name of the object to replace in addition to the index. For example, /templates//anps/AP1 would replace the application profile named AP1

? 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 value field for remove operations.

The following two examples 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.

Guidelines and Limitations

When using PATCH API, the following guidelines apply:

? You cannot use the PATCH API to change a template name, because multiple references in the fabric must be updated. Use PUT request instead.

For site local schema objects, refer to the Site ID and Template name combination as -, for example /sites/5b7d29c2a7fa00a7fae9bbf3-SampleTemplate/epgs

? You can reference objects using index or name.

Prior to Release 3.3(1), many objects could only be referenced by their index in the schema.

For example, if you had multiple subnets and you wanted to update the third one, you would have to use the following code with index 2:

[ { "op": "replace", "path": "/templates/Template1/externalEpgs/epgName/subnets/2/ip", "value": "2.2.2.2/24" }

]

Starting with Release 3.3(1), any objects which had to be referenced by an index can now also be referenced using their name or unique identifier. For some objects, which don't have a name or ID, you will need to continue to use an index.

Note You must continue using index for domainAssociation objects, as the dn fields can contain multiple slash (/) characters and cannot be easily identified within the full path string.

References by index remain valid for compatibility with existing scripts

Similar to the previous examples, you can now update any subnet by simply providing its IP address and mask:

[ { "op": "replace", "path": "/templates/Template1/externalEpgs/epgName/subnets/1.1.1.1/24/ip", "value": "2.2.2.2/24"

Using the REST API 5

PATCH Requests

Using the REST API

} ]

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:

PATCH

Request 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": [],

Using the REST API 6

Using the REST API

PATCH Requests

"contracts": [], "filters": [], "externalEpgs": [], "serviceGraphs": [], "intersiteL3outs": [] } ] }

Remove an Object Using PATCH Request (VRF Example)

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:

PATCH

Request payload:

[{ "op": "remove", "path": "/templates/Template1/vrfs/vrf1"

}]

Request response:

{ "id": "5c4b55db1a00003422f2215e", "displayName": "SampleSchema", "templates": [ { "name": "Template1", "displayName": "T1", "tenantId": "0000ffff0000000000000010",

Using the REST API 7

PATCH Requests

Using the REST API

"anps": [], "vrfs": [], "bds": [], "contracts": [], "filters": [], "externalEpgs": [], "serviceGraphs": [], "intersiteL3outs": [] } ] }

Remove an Object Using PATCH Request (staticPort Example)

An additional example of using PATCH request to remove a static port.

Original schema:

{ "id": "601acfed38000070a4ee9ec0", "displayName": "Schema1", "description": "", "templates": [ { "name": "Template1", "displayName": "Template 1", "tenantId": "0000ffff0000000000000010", "anps": [ { "name": "AP1", "displayName": "AP 1", "anpRef":

"/schemas/601acfed38000070a4ee9ec0/templates/Template1/anps/AP1", "epgs": [ { "name": "EPG1", "displayName": "EPG 1", "epgRef":

"/schemas/601acfed38000070a4ee9ec0/templates/Template1/anps/AP1/epgs/EPG1", "contractRelationships": [], "subnets": [], "uSegEpg": false, "uSegAttrs": [], "intraEpg": "unenforced", "prio": "unspecified", "proxyArp": false, "preferredGroup": false, "bdRef":

"/schemas/601acfed38000070a4ee9ec0/templates/Template1/bds/BD1", "vrfRef": "", "selectors": [], "epgType": "application"

} ] } ], "vrfs": [ { "name": "VRF1", "displayName": "VRF 1", "vrfRef": "/schemas/601acfed38000070a4ee9ec0/templates/Template1/vrfs/VRF1", "l3MCast": false, "preferredGroup": false,

Using the REST API 8

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download