It's easy to forget that a product with a nice user interface such as Intersight also has a robust API. In fact, the user interface is actually a subset of Intersight's capabilities. You can use the API to automate some tasks, define your entire infrastructure as code, or retrieve and filter information to generate reports formatted exactly the way you want to see them. Imagine the usefulness of a short script that could display which server policies have been modified in the last week (and who modified them) or a script that could display the model name and serial number of every server whose locator LED is turned on. In this blog, I'll provide an introduction to the Intersight API and how to use the API browser to experiment with the API.
The Intersight API is based on the OpenAPI specification. Tools available for the OpenAPI standard enable the Intersight engineering team to auto-generate API documentation and SDKs (software development kits) for Intersight in Python, PowerShell, Ansible, and Terraform. I'll cover using the SDKs in future posts. In this blog, I'll focus on the API browser. The API browser provides a web-based interface for perusing the long list of API endpoints and executing them without writing a single line of code. It's a great way to familiarize yourself with the format for requests and responses.
Every Intersight API request requires authentication via an API key ID and API secret. The Intersight API browser handles authentication for you seamlessly. We won't be explicitly using any keys for this blog.
Every managed object in Intersight is given a unique identifier known as a Moid (managed object ID). If you browse to the detailed view of any managed object (such as a policy, organization, or role), you'll find the Moid is actually in the URL of your web browser. For example, this could be the URL for an organization in Intersight:
intersight.com/an/system/an/settings/organizations/5ddf1d456972652d30bc0a10The Moid is 5ddf1d456972652d30bc0a10. The Moid is relevant to this conversation because that's how the Intersight API refers to objects. If you want to create an NTP policy, you'll need the Moid of the organization in which you want to create the policy. If you want to assign a policy to a server profile, you'll need the Moid of the policy and the profile. Because Moids are so fundamental to the Intersight API, I'll use retrieving a Moid for an organization as the use case for this blog.
To follow along with this blog, you'll need access to an Intersight account. You can use your own, or use this one provided by Cisco dCloud. I'll use Cisco dCloud. The first step is connect to Intersight and authenticate. Intersight has a lovely UI, but we are not interested in that right now. Go to the Help Center as shown below.
From the Help Center, there is a Getting Started section in the middle of the page. In that section, click on API Documentation as shown below.
The final step is to click on API Reference in the top menu bar as shown below. To avoid all those clicks in the future, note that you can simply browse to https://intersight.com/apidocs/apiref (if you're using SaaS).
You should now see the API browser. If you've done any scripting with other Cisco products such as Webex or Meraki, you've seen an API browser similar to this one. The API browser is a graphical means of experimenting with the API without having to write any code.
In the top right corner of the screen, you'll see your user account, which means you have been authenticated. If you're using the Cisco dCloud Instant Demo to follow along, your account will be in the form intuser-XXXXX@cat-dcloud.com. Remember that you can only perform API calls that are allowed for your user account. For the Cisco dCloud Instant Demo, that is read-only.
Along the left side of the screen is a list of all of the API endpoints. If you start to scroll through the list, you'll see that there are "tons" of endpoints (that's the technical term for more than I'd like to count). So how do you find what you're looking for? The search bar is quite handy. Type the word audit and the list will filter to two endpoints, making it much easier to figure out which endpoint is the right one to search through Intersight's audit records.
Again, I'm going to retrieve the Moid for an organization in this blog. If you're going to create any profiles, pools, or policies, you'll first need to know what organization you want to create them in. Therefore, getting a list of organizations in your Intersight account is a type of "hello world" exercise for getting started with the Intersight API. In the search bar, type the word organization.
The endpoint we need is organization/Organizations. If you expand that as shown in the picture above, you'll see that there is a description of the endpoint along the top. On the left side of the screen is a list of operations you can perform: GET, POST, PATCH, and DELETE. When tackling a new API, I always start by reading (GET) a resource to minimize the "opportunity" to make a mistake that could affect my environment.
Notice that there are two GET methods. One will return a list of organizations, and one will retrieve the details for the organization whose Moid you specify. We want a list (since we don't know the Moid yet), so select the first GET method.
The middle part of the screen contains documentation, and the right side of the screen allows you to execute API calls without writing code. Notice that there is a Send button. Clicking the Send button will Send a GET /api/v1/organization/Organizations to Intersight. Let's click Send. The API browser is such a helpful tool! It creates the HTTP headers for us seamlessly and then displays the output (the return payload) from the API call in a nice JSON format.
As shown in the above image, the data returned by Intersight is very detailed. But we just want a list of organization names in the Intersight account. We don't need to know who owns each organization or when it was created. If we were writing a script in Python or PowerShell, this would be easy to filter programmatically, but visually this is difficult to read as a human. We need a way to select only the Name of each organization, and thankfully the Intersight API provides such a mechanism.
The middle section of the API browser documents different query parameters that can be used. It says that $select "specifies a subset of properties to return." That's exactly what we need. Above the Send button is a hyperlink to add a Query Parameter. If you click that, you can specify the key ($select) and the value (Name) for the parameter. In other words, we are telling the Intersight API to return a list of organizations, but to select only the Name property for the return payload. Let's click Send again.
Now Intersight returns a much more readable list. Note that the API always returns the ClassId, Moid, and ObjectType for each query, even if you didn't ask for it. Typically our next step would be to create a policy, pool, profile, or user role, all of which require the Moid of the organization in which they should be created. We have what we need (the Moid of a specific organization), so that concludes this "hello world" exercise.
In this example, I used a very simple query parameter ($select). Several more query parameters are available to search and sort with text, numerical, or date operators. There are also capabilities to perform operations like aggregation. Aggregation be used to group alarms by severity or group servers by model name (just to name two trivial examples). You can always find details about the query syntax in the Intersight help. If you're writing some automation in Python or PowerShell, you are probably already comfortable with that language and are more likely to search, filter, sort and aggregate with the constructs built into those languages. You might not choose to use the advanced query parameters built into the API, but you should know that they exist if you prefer that the payload processing be done by Intersight rather than your local machine.
I hope you found this blog useful. Please post a comment with any other programmability/automation content you would like to see here.
