Secure Firewall REST API Introduction

Introduction

This document describes the REST API configuration introduction for Cisco Secure Firewall using Firewall Management Center API explorer.

Additional Information

REST API is an Application Programming Interface that can communicate based on RESTful principles. REST APIs communicate via HTTP requests and perform Create, Read, Update, and Delete (CRUD) operations within a resource. Configuration through REST API enables a great deal of possibilities to automate and streamline the way you configure Secure Firewall devices.

The main advantages of using REST API are:

• Scalability - Since Operations can be extended to several resources.
• Flexibility - Easy to implement in different software development environments; like most APIs, it uses XML, JSON, and HTTP.
• Automation - You can streamline configuration processes for several devices at a time by performing configuration changes in bulk, reducing time-consuming repetitive configuration tasks.

REST API relies on the same authentication as the FMC/FDM and uses OAUTH2.0. Each function in the REST API maps to the same permissions in FMC and FDM.

Configuration

API Explorer Walk-Through

REST API is enabled by default within FMC. You can confirm it is enabled by navigating to System > Configuration > REST API Preferences.

Enable Rest API

FMC and FDM have a built-in interface called API Explorer, which is a helpful tool for reviewing the capabilities and functions of REST API. For FMC, API Explorer can be accessed with this URL; https://<management_center_IP_address>/api/api-explorer.

Login using FMC GUI credentials:

Sign in using your FMC GUI credentials

Once accessing the API explorer, the homepage is displayed. Here you can find the top ribbon, domains, and configuration sections. In the top right corner, you can find the version information as well as helpful resources:

Top Ribbon

Next, find all the configuration sections, starting with the Domains. Choosing this dropdown displays all existing FMC Domains.

Domains

Configuration sections and capabilities are shown next, including features that are supported by FMC:

Configuration Sections

Finally, at the bottom of the page, you can find the Schemas section. Here you can have a look at some of the configurations in JSON for additional supported features that you can use as a reference to build your HTTP requests for these features:

Schemas

Using API Explorer

Now, going back to the configuration sections, navigate to Devices:

Devices configuration

REST API for FMC supports the next HTTP methods. Note that each one of them performs a CRUD operation:

• GET – Read

• POST – Create

• PUT – Update/Replace

• DELETE – Delete

The Unified Resource Identifier (URI) accompanies each of these methods with the corresponding path to each object:

/api/fmc_config/v1/domain/{domainUUID}/devices/devicerecords

By choosing one of these methods, you can expand and see the parameters included in your GET HTTP request:

• Filter
• Offset
• Limit
• Expanded
• Domain Universally Unique Identifier (UUID)

GET devices/devicerecords

Note: Domain UUID is crucial when generating the HTTP requests since each object has a unique identifier assigned, and such is required to perform operations.

Device Records Domain UUID

Copy the Domain UUID:

e276abec-e0f2-11e3-8169-6d9ed49b625f

Next, you can see the Responses section, where you can find the Curl and Request URL along with the default Server Response to this method and some server response examples.

Responses Section.

Test FMC API Explorer GET Method

Now you are ready to test API explorer functionality by clicking Try it out:

Select Try it out

For this particular HTTP GET request (of devices, device records), you are not required to include any other UUID or additional parameters and you can choose Execute:

Select Execute

FMC returns a Server Response 200 if the HTTP GET request was successful and the Response body contains Device information for all registered devices in your FMC.

200 GET Response Output.

From this output, notice that there is one FTD managed by this FMC, named FTDv-703.

GET Device Records Domain UUID

You can write down the ID value as it is used in order to access the API requests targeted to this FTD in particular. Copy the ID:

"name": "FTDv-703"
"id": "6bad6bbc-0b05-11ee-9a47-84ecf73b3ccf"

As a final example, you can retrieve all Interface configurations of a particular Managed device (FTDv-703) by using the UUID of a device (obtained from the earlier response) in this method:

"id": "6bad6bbc-0b05-11ee-9a47-84ecf73b3ccf"

Navigate to GET - Devices > Device records > physicalinterfaces.

/api/fmc_config/v1/domain/{domainUUID}/devices/devicerecords/{containerUUID}/physicalinterfaces

FMC replies (with the Server Response output) and you can see that this device (FTD) has two data Interfaces and a diagnostic interface configured with their corresponding UUID and configurations.

GET Device Records Physical Interfaces Response.

From Response body:

"type": "PhysicalInterface",
"id": "005056B3-9582-0ed3-0000-004294967553",
"name": "GigabitEthernet0/0"

"type": "PhysicalInterface",
"id": "005056B3-9582-0ed3-0000-004294967554",
"name": "GigabitEthernet0/1"

"type": "PhysicalInterface",
"id": "005056B3-9582-0ed3-0000-004294967555",
"name": "Diagnostic0/0"

The previous tree-like structure and the logic of accessing the HTTP methods are applicable to all objects. Proceeding from general to specific UUID, you can read, modify, or add configuration changes to the FMC and specific managed devices.

URI Structure.

The FMC API explorer can be of great use as a guide or reference in order to view the supported features and configuration methods, so you can design and customize your code for configuration deployments.

You can also interact with FMC API using multiple API platforms like Postman or from a local host through Python or Perl script.

Note: You can visit the Secure-Firewall Repository in Github in order to view a great deal of Templates and Automation Resources.