Demonstrate Navigation through Secure Firewall's API-Explorer

Introduction

This document describes the navigation through Application Programming Interface (API) explorer of Cisco FMC and Cisco FDM.

Prerequisites

Basic understanding of REST API.

Requirements

It is required for this demonstration to have access to the Firepower Management Center (FMC) GUI with at least one device managed by this Firepower Management Center (FMC). For the FDM part of this demonstration, it is needed to have a Firepower Threat Defense (FTD) managed locally to have access to the FDM GUI.

Components Used

• FMCv
• FTDv
• FTDv Locally managed

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Review Navigation through FMC API Explorer

To access the FMC API explorer, navigate to the next URL:

https://<FMC_mgmt_IP>/api/api-explorer

You must log in with the same credentials used for the FMC GUI. These credentials are entered in a window similar to the next one when you enter the API explorer URLs.

Once logged in, it is seen that the API queries are divided by categories corresponding to the possible calls you can make using APIs.

Note: Not all configuration functions available from the GUI or CLI are available through the APIs.

When clicking a category, it expands showing you the different calls available for this category. These calls are shown along with their respective REST methods and the Universal Resource Identifier (URI) of that call.

In the next example, you make a request to see the access policies configured in the FMC. You click the corresponding method to expand it, then click the Try it out button.

Something to emphasize is that you can parametrize your queries with the available parameters in each API call. Only those with red asterisks are mandatory, the others can be left empty.

For example, the domainUUID is mandatory for all API calls, but on the API Explorer this fills automatically.

Next step is to click Execute to make this call.

Before clicking Execute,  you can see examples of responses to the calls to get an idea of the possible responses you can get depending on whether the request is correct or not.

Once the API call is executed, you obtain, together with the response payload, the response code. In this case 200, which corresponds to an OK request. You also get the cURL and the URL of the call you just made. This information is useful if you want to make this call with an external client/software.

The answer obtained returns the ACPs configured in the FMC along with their objectID.  In this case, you can see this information in the red box in the next image:

This objectID is the value you enter in calls that require reference to this ACP. For example, to create a rule within this ACP.

The URIs that contain values between curly brackets {} are values required to make this call.  Remember that domainUUID is the only value that is automatically filled.

The values required for these calls are specified in the call description. To create rules for an ACP, you require the policyID, as you can see in the next image:

This policyID is entered in the field specified as containerUUID, another required field for POST methods is the payload or request body. You can use the examples given to modify to your needs.

Example of modified payload:

{ "action": "ALLOW", "enabled": true, "type": "AccessRule", "name": "Testing API rule", "sendEventsToFMC": false, "logFiles": false, "logBegin": false, "logEnd": false, "sourceZones": { "objects": [ { "name": "Inside_Zone", "id": "8c1c58ec-8d40-11ed-b39b-f2bc2b448f0d", "type": "SecurityZone" } ] }, "destinationZones": { "objects": [ { "name": "Outside_Zone", "id": "c5e0a920-8d40-11ed-994a-900c72fc7112", "type": "SecurityZone" } ] }, "newComments": [ "comment1", "comment2" ] }

Note: The available zones, together with their IDs, can be obtained using the next query.

Once you execute the previous call, you get a 201 response code, indicating that the request has succeeded and has led to the creation of the resource.

Finally, you must make a deployment for these changes to take effect in the FTD whose ACP was modified.

For this, you have to obtain the list of devices that have changes ready to be deployed.

The example contains a pair of devices configured in High Availability. You must obtain the ID of this HA, in case of being a standalone device, you must obtain the ID of that device.

The query needed to obtain the device ID of the HA is as follows:

With the device ID and the deployment version number, you can modify the payload of the next call example to make the call to perform this deployment.

Once this call is executed, if everything is correct, you get a response with code 202.

Review Navigation through FDM API Explorer

To access the FDM API Explorer, it is possible to use a button on the FDM GUI to go directly to it, as shown in the next image:

Once in the API Explorer, you notice that the queries are also divided into categories.

To expand a category, you must click it, and then you can expand each of the operations by clicking on any of them. The first thing found inside each operation is an example of an OK response for this call.

The next thing you see are the parameters available to constrain the responses of the call you make. Remember that only the fields marked as required are mandatory to make such a call.

Finally, you find the possible response codes that this call can return.

If you want to make this call, you must click Try It Out. To find this button, you have to scroll down until you find this button since it is located at the bottom of each call.

When you click the Try It Out button, if it is a call that does not require more fields, it executes immediately and gives you the response.

Troubleshoot

Each call generates an HTTP response code and response body. This helps you to identify where the error is.

The next is a common error that occurs when the session has expired, indicating that the token is invalid because it has expired.

The next are examples of HTTP response codes that calls can return:

• 2xx series: Success. There are several status codes: 200 (GET and PUT), 201 (POST), 202, 204 (DELETE). They indicate a successful API call.
• 30x series: Redirection. Can be used when a client originally used HTTP and was redirected to HTTPS.
• 4xx series: Client-side failure in the API call that was sent from the client to the server. Two examples include a 401 status code, indicating the session is not authenticated, and a 403 code, indicating a forbidden access attempt.
• 5xx series: Server, device, or service-side failure. This could be the result of the device API service being disabled, or inaccessible over the IP network