REST API Request Format

After the object payloads are properly encoded as XML or JSON, they can be used in create, read, update, or delete operations on the REST API. Figure 9-14 shows the syntax for a read operation from the REST API.

Figure 9-14 REST Syntax for Read Operation

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 and access details of the APIC. Next in the request URI is the literal string /api, indicating that the API will be invoked. Generally, read operations are for an object or class, as discussed earlier, so the next part of the URI specifies whether the operation will be for an MO or class. The next component defines either the fully qualified domain name (FQDN) being queried for object-based queries or the package and class name for class-based queries. The final mandatory part of the request URI is the encoding format: either .xml or .json. The REST API supports a wide range of flexible filters, useful for narrowing the scope of your search to allow information to be located more quickly. The filters themselves are appended as query URI options, starting with a question mark (?) and concatenated with an ampersand (&). Multiple conditions can be joined together to form complex filters.

Both create and update operations in the REST API are implemented using the POST method so that if an object does not already exist, it will be created, and if it does already exist, it will be updated to reflect any changes between its existing state and desired state. Create and update operations use the same syntax as read operations, except that they are always targeted at an object level, because you cannot make changes to every object of a specific class (nor would you want to). The create or update operation should target a specific managed object, so the literal string /mo indicates that the DN of the managed object will be provided, followed next by the actual DN. The payload of the POST operation will contain the XML- or JSON-encoded data representing the MO that defines the Cisco API command body. Figure 9-15 shows a sample REST payload.

Figure 9-15 REST Payload