controller provides interactive, northbound Representational State Transfer
(REST) API documentation. You can use the REST API documentation to help you
integrate the controller with your larger network management system and
administer your network.
The controller displays northbound REST API documentation based upon
services that have been installed in the service catalog on the root.
To access the
northbound REST API documentation, from the
Global toolbar, click
The REST API
documentation is based on Swagger 1.2 specifications.
Figure 1. API
northbound REST API documentation provides:
information about the northbound REST APIs terms of services and the Cisco
developer community website:
Service—Review the terms and services for accessing the server
where the APIs are located.
DevNet—Access the Cisco developer community website. This website
offers developer information, community forums, a developer sandbox, and other
A list of
supported northbound REST APIs used by the controller and organized by
IP Pool Manager
Network Plug and Play
Role Based Access
applications with an active service running display in the menu list.
A list of
supported methods for each northbound REST API including:
retrieve a resource.
the state of a resource or to update it.
remove or delete a resource.
Methods of the
Show/Hide—Displays or hides supported methods of the
API (GET, POST, PUT, and DELETE).
Operations—Displays the supported methods of the API (GET, POST,
PUT, and DELETE).
Operations—Displays an expanded view of the methods of the API
Implementation Notes—Brief descriptions of what the
northbound REST API does, including some specific details of the
Response Class—Model and Model Schema views, as well
as a Response Content Type:
Parameters—Parameter, Description, Parameter Type,
Data Type definitions (string, integer, or model), as well as input fields if
required for testing.
Error Status Codes—HTTP status code and reason
Raw content for the external Swagger UI (user
provided) to access the northbound REST API. Content is provided in text file
To get a better
understanding of the northbound REST APIs, you can run sample methods and get
resultant outputs. For more information, see
Testing the Cisco APIC-EM APIs.
method type returns a 404 response code if it fails, or the following response:
The following are general guidelines
for the supported HTTPS methods for the
Each method is used as an operation on a single resource
Each resource is
expressed as a singular noun (for example: network-device, link, interface,
The resource is
referenced in the HTTPS method by an ID number (not by name)
number of entries returned by a GET API is 500 (default). No API should provide
more than 500 (default) entries in a single call.
A CRUD (Create,
READ, Update, Delete) operation on all resources is not allowed in a single API
RESTful Services HTTP Response Codes
services return common HTTP response codes as described in the tables below. In
addition to the status codes returned in the response header, each response may
have additional content (in JSON file format) according to the nature of the
Table 1 Success (2xx)
request was successful. The result is contained in the response body.
POST/PUT request was fulfilled and a new resource has been created. Information
about the resource is in the response body.
request was accepted for processing, but the processing has not been completed.
request was successful, however no content was returned.
request included a Range Header, and the server responded with the partial
content matching the range.
Table 2 Client Error
made a request that the server could not understand (for example, the request
syntax is incorrect).
client's authentication credentials included with the request are missing or
recognizes the authentication credentials, but the client is not authorized to
perform this request.
client made a request for a resource that does not exist.
resource is in a conflicted state (for example, an edit conflict where a
resource is being edited by multiple users). Retrying the request later might
Unsupported Media Type
sent a request body in a format that the server does not support (for example,
XML to a server that only accepts JSON).
Table 3 Server Error
Internal Server Error
server could not fulfill the request.
server has not implemented the functionality required to fulfill the request.