With the 6.4 release, the Firepower Management Center (FMC) supports the Open API standards for the API specification. The Open API Specification site quotes the following about Open API standards – “The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.” The FMC Open API support adds new capabilities that make integration with the FMC much easier and simpler.
This blog contains information on accessing the new API Explorer page, navigating the explorer pages for supported API operations, specific examples for applicable operations, executing or trying out an operation, information on the API model and downloading the specification, and information on various open source tools for the API client development.
The Open API Specification (OAS) brings in powerful new capabilities in the way you consume the APIs. Let’s delve further to see how you can access these APIs in FMC. The original URL “https://<<your-server>>/api/api-explorer” takes you to the new API explorer screen that leverages the Open API standards. The new FMC API Explorer screen uses the Swagger UI to render this page.
Let’s have a quick look at the various options on this page.
- Download Spec: This is a direct link to download the Open API specification for the whole of FMC. It also thoroughly describes all the supported API operations.
- Legacy Explorer: This links to the legacy API explorer interface page, which has all API information in the older format.
- Logout: A link to log out from the page.
- REST URLs and Supported Methods: This is an information section that provides references and quick links for more resources.
- Domains: A domain selector that allows you to choose the domain on which you want to perform your API calls.
- API Resource Section: This section provides complete details on the supported APIs and a convenient way of trying them out.
Let’s now delve deep into the API resource section that contains all the information on supported operations and their models.
The page consists of a list of top-level sections – Devices, Policy Assignments, Device HA Pairs, and so on. The section is divided based on the top-level area under which the API resources are available. For example, the Devices section contains all APIs related to device operations; the Policy Assignments section has APIs that can assign policies to different targets, and so on. Clicking a top-level section header displays the list of operations and URLs that are supported under it. Clicking further on the corresponding URL opens the specific REST API with more details.
As an example, let’s explore the GET /api/fmc_config/v1/domain/{domainUUID}/object/hosts/{objectID} REST API call in detail using the API explorer. The host is essentially a host network object which is contained within the Objects section. Clicking on the GET operation in the Object sections opens more details around it.
The GET page includes a short description of the GET object, a Try it out button to try out the GET operation on the FMC, and the query and path parameters that are required to try out this operation successfully. Let’s scroll down a bit further to see more details from the Responses section.
The Responses section contains some useful information like the supported examples for the operation, the response code (200 in this case), and the Model link beside the Example Value that provides more details about the Model itself.
|
Note: Any applicable Cisco provided example content irrespective of the type of HTTP operation – GET, PUT, POST or DELETE is always mentioned in the responses section of the operation in question. |
Let’s now explore the model link.
Choosing the Model link displays a comprehensive model description of the model attributes used in this operation. The second-level models like Metadata can be expanded for more details.
To try out an actual operation, click the Try it out button. Fill in the relevant data and click the Execute button, which displays the results in the responses section. For example, the domainUUID is automatically populated based on the Domain that is selected in the top of the page.
|
Note: All operations are always performed on the actual server data on the FMC from where the API Explorer is launched. |
Finally, let’s have a quick glimpse at the open API specification itself. As mentioned at the beginning of this overview, you can use the Download Spec to download the Open API specification for the whole of FMC. It thoroughly describes all the supported API operations to ease the API client development. The FMC API supports the Open API standards version 2.0.
There is also a bunch of open source tools available to ease the process of developing API clients to integrate with the FMC API using the Open API specification. Here’s a short list of some of the open source projects that can be of some help (listed in no specific order):
- Swagger Code Gen: This can be used to auto-generate documentation, and API clients in different languages by using the Open API specification file.
- Bravado: This is a Python client library for API that supports Open API version 2.0.
- OpenAPI Generator: This generates clients, servers, and documentation from OpenAPI 2.0/3.x specifications.
- Go-Swagger: This can be used for Go-based client generation.
|
Note: The tools mentioned here are not specifically evaluated or endorsed for use with the FMC Open API specification. It is the responsibility of the consumer to evaluate specific tools based on their individual need. |
Hope you found this blog useful and that it helped you to explore the possibilities with FMC Open API support.
Cheers
- Vijaya Raghavan S V
