About the API Explorer

About the API Explorer

The API Explorer provides a limited interface for the REST API as well as giving a view of the abilities of the REST API.

The API Explorer resides on the management center, and can be accessed via the management center at:

https://<management_center_IP_or_name>:<https_port>/api/api-explorer

Version 6.4 uses a new API Explorer, based on the OpenAPI Specification (OAS). You can still access the legacy API Explorer if you prefer.

As part of the OAS, you now use CodeGen to generate sample code.

This explorer provides the list of APIs available on the management center, and their details.

Authentication to the API Explorer

The REST API relies on the same authentication as the management center. Each function in the REST API maps to permissions in the management center.

You can log into the API Explorer using any account on the management center, but you will only be able to perform the functions for which the account has permissions. For more information on setting permissions for user roles, see the Firepower Management Center Configuration Guide.

The first time you connect to the API Explorer you may receive an error that the connection is not secure due to an invalid certificate. You will need to add an exception in your browser to use the certificate and accept the connection.

Logging into API Explorer

The REST API uses the same authentication and permission model as the management center. See the Firepower Management Center Configuration Guide for more information.

Before you begin

Make sure you have an account on your management center with the required permissions to perform the tasks you want to perform using the REST API.

Procedure

Step 1

Navigate to the following URL: https://<management_center_IP_or_name>:<https_port>/api/api-explorer

If you experience an extended load time for the logon screen when using a Firefox browser, enter about:support in the search bar and click the Refresh Firefox option, then view the management center interface with self-signed certificates in the same Firefox browser. For more information, see https://support.mozilla.org/en-US/kb/refresh-firefox-reset-add-ons-and-settings.

Step 2

Log in with your username and password and click "Sign In"

What to do next

Locate the desired resource and request.

Setting the Domain

The REST API can perform functions globally, in the default domain, or in specific domains.

Before you begin

You must have a configured management center, an account with permissions to access the REST API in one or more domains configured on your management center.

Procedure

In the upper right, drop down the Domains menu and select the desired domain.

What to do next

Locate the desired resource and request type.

Accessing the Legacy API Explorer

The API Explorer has changed for 6.4.0. While the newer API Explorer retains nearly all of the previous functionality, some users may prefer the older interface.

Before you begin


Note

The Legacy Explorer will be removed in future releases of management center. Please use the Open API Specification for access to current REST API functionality in the future.

Make sure you have an account on your management center with the required permissions to perform the tasks you want to perform using the REST API.

Log in to the API Explorer at https://<management_center_IP_or_name>:<https_port>/api/api-explorer.

Procedure

In the upper right-hand corner click on Legacy Explorer.

What to do next

Use the Legacy API Explorer as you would normally.

Obtaining Sample Code with CodeGen

You can use the CodeGen utility on the Open API Spec to generate sample code in a number of different languages. This utility is an open-source tool you can download online. The resultant code is meant primarily as an educational and bootstrapping tool.

The CodeGen utility creates sample code for the entire Open API Spec. As such, it generates sample code for every allowed method and endpoint in the REST API. The sample code can be in a variety of languages, including HTML, Perl, Python, and Java.

For complete documentation of the CodeGen utility go to https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/

Downloading the Open API Spec

The Open API Spec is a standardized specification of a REST API. The Open API Spec for the management center REST API contains details about the endpoints, fields, parameters, and requirements of the API. You can use the API Spec to generate sample code as well as find specific information about API functionality.

The Open API Spec is a JSON file. It can be read by most text editors.

Before you begin

Have an account on the management center which is able to access the API Explorer.

Make sure that your browser is able to download from sites with self-signed certificates.

Procedure

Step 1

Navigate to the following URL: https://<management_center_IP_or_name>:<https_port>/api/api-explorer

Step 2

Click on Download Spec in the upper right corner. Depending on your browser configuration, you will either be given a prompt to save the file, or be shown the file directly.

Step 3

Save the file. Be sure to note the destination and filename.

What to do next

Run the CodeGen utility on the downloaded file.

Generating Sample Code with the CodeGen Utility

The Swagger CodeGen utility allows you to generate sample code from an Open API Spec. This sample code can be in a variety of languages including Java, HTML, Python, and Perl.

Before you begin

Download the Swagger CodeGen Utility. It can be found at https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/

Have a Jave Runtime Environment installed on your computer

Download the management center REST API Open API Spec

Set environment variables to allow you to run the CodeGen utility

Procedure

From the command line, run the command java -jar ./swagger-codegen-cli-<VERSION>.jar generate -o <OUTPUT_PATH> -l <LANGUAGE> -i <OPEN_API_SPEC_FILE>

Example:

java -jar ./swagger-codegen-cli-2.3.1.jar generate -o C:\work\code\api_schema\html -l html -i fmc_swagger.json

<VERSION> is the specific version of the CodeGen utility you are using. It must match the filename of the CodeGen .jar file.

<OUTPUT_PATH> is the path to which you want to output the generated code.

<LANGUAGE> is the language which you want CodeGen to generate. Suggested options include html, java, perl, and python. Other options are possible, check the CodeGen documentation for the complete list of choices.

<OPEN_API_SPEC_FILE> is the Open API Spec file which you downloaded. This is the source from which CodeGen is generating example code. Without it, CodeGen cannot provide output.

What to do next

Find the generated code in the output path and use as desired. Generated code should be considered an example, and may not perform as desired unless modified to meet your needs.

Viewing API Parameters

Each resource has a set of parameters and fields associated with it. You can view the parameters and fields by performing any of the supported operations for that resource within API Explorer.

Before you begin

You must have a configured management center and an account on that center with the permissions required to use the desired REST API functions.

Procedure

Step 1

Select the desired resource.
Step 2

Select one of the supported operations for that resource.