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.
This chapter contains the following sections:
Cisco UCS Director offers a REST API that enables applications to consume or manipulate the data stored in Cisco UCS Director. Cisco UCS Director REST API (hereafter, simply "the REST API") is a lightweight framework that requires little overhead for an application to use.
Applications use HTTP and HTTPS requests from the REST API to perform Create/Read/Update/Delete (CRUD) operations on Cisco UCS Director resources.
Cisco UCS Director REST API is a language-independent interface that can be used by any program or script capable of making HTTP or HTTPS requests. Use the REST API when you want to invoke operations on Cisco UCS Director from a separate program or process.
Applications can use the REST API to do the following:
Retrieve Cisco UCS Director reports on physical and virtual devices, networks, appliances, groups and users, policies, resource accounting, funds, and other monitored entities within your Cisco UCS domains.
Invoke Cisco UCS Director Orchestrator workflow and task operations.
Invoke additional operations specific to Cisco UCS Director.
Because a REST API client interacts with Cisco UCS Director using standard HTTP or HTTPS requests and responses, the REST API responses are compatible with any web browser. Many programming languages have libraries devoted to creating and sending HTTP requests and handling HTTP responses.
Most of the REST API calls send and return data in the request or the response, respectively. These data payloads may be formatted in one of two ways depending on the REST API call. Some of the REST API calls use a JavaScript Object Notation (JSON) payload, while others use an XML payload. You probably have to use both for any reasonably complex application.
A JSON-based REST API call is a plain HTTP request and response with a JSON payload. JSON is a lightweight text-based open standard designed for human-readable data interchange. JSON represents simple data structures and associative arrays. Your application directly invokes the JSON-based API without using any specialized REST API libraries, and parses JSON data using any means native to your application.
An XML-based REST API call is also an HTTP request and response, but requires that your application include the Cisco UCS Director REST API library jars and that your application use the API-defined JavaBeans (also called "plain old Java objects, or POJOs) in the REST payload. The API jars enable you to marshal and unmarshal the payload of the XML message to and from a Java object respectively.
Authorization in the REST API is enforced by requiring that only registered users of Cisco UCS Director are able to make API requests. When a user is created and registered on Cisco UCS Director, the user is assigned a unique REST API access key. This key must be provided in the HTTP or HTTPS request header when making an API call. The user then has access to the same data and operations via the REST API that it has in Cisco UCS Director.
For system requirements and information about how to set up a development environment, install libraries, and begin using the REST API, see the Cisco UCS Director REST API Getting Started Guide.
For annotated examples of using the REST API, see the Cisco UCS Director REST API Cookbook.
For a complete list of every Cisco UCS Director REST API function, see the Cisco UCS Director REST API URI Reference.