The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Cisco APIC-EM 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.
Note | The controller displays northbound REST API documentation based upon services that have been installed in the service catalog on the root. |
Note | The REST API documentation is based on Swagger 1.2 specifications. |
The interactive northbound REST API documentation provides:
Links to information about the northbound REST APIs terms of services and the Cisco developer community website:
File
IP Pool Manager
Network Plug and Play Service
Policy Administration
Role Based Access Control
Scheduler
Task
Topology
Note | Only applications with an active service running display in the menu list. |
A list of supported methods for each northbound REST API including:
Methods of the API:
Show/Hide—Displays or hides supported methods of the API (GET, POST, PUT, and DELETE).
List Operations—Displays the supported methods of the API (GET, POST, PUT, and DELETE).
Expand Operations—Displays an expanded view of the methods of the API including:
Implementation Notes—Brief descriptions of what the northbound REST API does, including some specific details of the implementation.
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 definitions.
Raw content—Provides Raw content for the external Swagger UI (user provided) to access the northbound REST API. Content is provided in text file format.
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.
The following table describes the supported HTTPS methods and structure for the Cisco APIC-EM.
HTTPS Method Type |
Structure |
---|---|
GET |
Use the following values with the GET method type: |
POST |
The POST method type returns a 409 response code if posting a duplicated resource, or the following response: {"response":"id-of-created-resource"} |
PUT |
The PUT method type returns the following response: {"response":"message-about-attributes-that-changed"} |
DELETE |
The DELETE method type returns a 404 response code if it fails, or the following response: {"response":"message-about-deletion"} |
The following are general guidelines for the supported HTTPS methods for the Cisco APIC-EM:
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, host, etc.)
The resource is referenced in the HTTPS method by an ID number (not by name)
The maximum 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 call.
External RESTful 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 request.
Status Code |
Description |
---|---|
200 OK |
The request was successful. The result is contained in the response body. |
201 Created |
The POST/PUT request was fulfilled and a new resource has been created. Information about the resource is in the response body. |
202 Accepted |
The request was accepted for processing, but the processing has not been completed. |
204 No Content |
The request was successful, however no content was returned. |
206 Partial Content |
The GET request included a Range Header, and the server responded with the partial content matching the range. |
Status Code |
Description |
---|---|
400 Bad Request |
The client made a request that the server could not understand (for example, the request syntax is incorrect). |
401 Unauthorized |
The client's authentication credentials included with the request are missing or invalid. |
403 Forbidden |
The server recognizes the authentication credentials, but the client is not authorized to perform this request. |
404 Not Found |
The client made a request for a resource that does not exist. |
409 Conflict |
The target 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 succeed. |
415 Unsupported Media Type |
The client sent a request body in a format that the server does not support (for example, XML to a server that only accepts JSON). |
Status Code |
Description |
---|---|
500 Internal Server Error |
The server could not fulfill the request. |
501 Not Implemented |
The server has not implemented the functionality required to fulfill the request. |
503 Service Unavailable |
The server is (temporarily) unavailable. |
You can test the Cisco APIC-EM northbound REST APIs in the API window.