Troubleshoot Object Creation Using FMC API Explorer

Introduction

This document describes how an API administrator can push Network, Port, and URL Objects in bulk to FMC using API Explorer.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Understanding of various REST API (Appplication Programming Interface) calls. (REST API Basics)
• Understanding API Explorer in FMC (Firepower Management Center) (About the API Explorer)
• Review of the FMC API Quick Start Guide
• Understanding of different types of Objects in FMC (Object Management in FMC)

Components Used

• Firepower Management Center that supports REST APIs (version 7.4 or higher) with REST API enabled
• API Explorer integrated in FMC

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.

Limitations

• FMC does not accept the name of the object to be greater than 64 characters.
• Object Name must not have space at the beginning of the object name and semicolon at the end.
• The payload cannot contain more than 1,000 entries in a single Bulk Push.
• Payload size cannot be more than 2MB in a single Bulk Push.

Background Information

REST APIs are increasingly popular due to the lightweight programmable approach that network managers can use to configure and manage their networks. FMC supports configuration and management using any REST Client and also using the in-built API explorer.

This article provides troubleshooting steps for resolving issues encountered when creating objects via the Firepower Management Center (FMC) API Explorer. Whether you are working with network objects, host objects, or FTD configurations, these steps can help identify common problems and implement effective solutions.

The JSON attributes that remains common among all the network object types are:

1. Value - This attribute provides information like Network value with CIDR, for instance, host object can have x.x.x.x as an IP and network can have x.x.x.x/<prefix> as subnet with CIDR.
2. Type -  This attribute provides information about the object type used to configure object (host, network, service, range and FQDN).
3. Name - This attribute provides the information about the name of the object
4. Description - This attribute can be used to provide some useful information or comment about the object
5. Overrideable - An object override allows you to define an alternate value for an object, which the system uses for the devices you specify. This is an optional attribute that can be used in creating objects.

Configuration

Enable API on FMC

Enable REST API on Cisco FMC. For detailed information on "How to enable REST API" and "Best Practices" refer Enable REST API on Cisco FMC

Navigate to System > Configuration > REST API Preferences > Select "Enable REST API"

The API Explorer resides on themanagement center, and can be accessed via themanagement centerat:

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

Note: If standard HTTPS port TCP 443 is used then safely remove ":<https_port" from the url.

Common Errors encountered

We are discussing the most common errors we encounter while using API explorer and POST method to create objects. The correct format for each Network Object is discussed after it.

1. Invalid access token:

JSON response for invalid access token

Note: This error is encountered when the session has expired. Reload FMC API explorer and re-authenticate.

2. Invalid format used:

{
  "name": "API_1",
  "type": "Host",
  "value": "10.5.3.20"
  "description": "Test Description"
}

Sample JSON request to create object

Failed JSON response due to missing comma

Note: This error is encountered mostly when there is a missing comma in JSON format. In the example ("value": "10.5.3.20") does not have a comma which caused this failure. Only the last Attribute in JSON format must not have a comma else it can cause failure.

3. Invalid Input used in object creation:

{
  "name": "net2",
  "value": "1.1.0.0/24",
  "overridable": false,
  "description": "Network obj 2",
  "type": "Network"
}

Failed JSON response for invalid type

Note: In this example object creation is attempted in Hosts category with JSON payload for Network Object and it resulted in error "Input type mismatch". Use correct format designated for each Network Object (Hosts, Network, FQDN, Service and Range).

4. Using GET method response payload for Object creation

{
      "links": {
        "self": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/hosts/00000000-0000-0ed3-0000-034359741703",
        "parent": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/networkaddresses"
      },
      "type": "Host",
      "name": "API_2",
      "id": "00000000-0000-0ed3-0000-034359741703"
}

GET request to fetch host objects

Failed JSON response due to missing value attribute

Failed JSON response where object is created in incorrect format

Note: In this example Value attribute is missing in the JSON payload fetched using GET method and expanded parameter is set to default. There are mandatory attributes that can be in JSON payload for object creation which is type, name and value for most of the network objects (hosts, network, range, service and FQDN). When creating object using the JSON payload of GET method, use only object related information which is inside items attribute and remove id attribute so that there is no UUID conflict.

Create Host Object

Single Host Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST and click Try it Out.

JSON format used to push single host object:

{
  "name": "Obj_API_100.1.1.1",
  "type": "Host",
  "value": "100.1.1.1",
  "description": "Host Object Pushed via API"
}

POST operation to create host object

Note: Use default "Bulk Parameter" while using POST operation to single host object.

Bulk Host Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST and click Try it Out.

JSON format used to push bulk host objects:

[
	{
	"name": "Obj_API_172.16.0.1",
	"type": "Host",
	"value": "172.16.0.1",
	"description": "Bulk API Operation"
	},
	{
	"name": "Obj_API_172.16.0.2",
	"type": "Host",
	"value": "172.16.0.2",
	"description": "Bulk API Operation"
	}
]

Sample JSON request to create bulk objects

Sample JSON Response after creating bulk objects

Note: When creating bulk host objects, select Bulk Parameter as True. In a single Bulk Push maximum 1000 entries can be created using POST method.

Create Network Object

Single Network Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST and click Try it Out.

JSON format used to push single network object:

{
  "name": "Obj_API_network",
  "value": "7.0.0.0/24",
  "overridable": false,
  "description": "Single Network object created",
  "type": "Network"
}

Sample JSON request to create single network object

Bulk Network Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST and click Try it Out.

JSON format used to push bulk network objects:

[
  {
    "name": "Obj_API_net1",
    "value": "1.0.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  },
  {
    "name": "Obj_API_net2",
    "value": "1.1.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  }
]

Sample JSON request to create bulk network objects

Note: When creating bulk network objects select Bulk Parameter as True. In a single Bulk Push maximum 1000 entries can be created using POST method.

Create Network Range Object

Single Network Range Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST and click Try it Out.

JSON format used to push single range object:

{
  "name": "Obj_API_TestRange",
  "value": "10.2.30.40-10.2.30.50",
  "type": "Range",
  "description": "Create Single Range Object"
}

Bulk Network Range Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/ranges > POST and click Try it Out.

JSON format used to push bulk range objects:

[
  {
    "name": "Obj_API_TestRange1",
    "value": "10.4.30.40-10.4.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_TestRange2",
    "value": "10.5.30.40-10.5.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  }
]

Note: When creating bulk range objects select Bulk Parameter as True. In a single Bulk Push maximum 1000 entries can be created using POST method.

Create FQDN Object

Single FQDN Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST and click Try it Out.

JSON format used to push single network object:

{
  "name": "TestFQDN",
  "type": "FQDN",
  "value": "cloud.cisco.com",
  "dnsResolution": "IPV4_ONLY",
  "description": "Create Single FQDN Object"
}

Bulk FQDN Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST and click Try it Out.

JSON format used to push bulk network objects:

[
  {
    "name": "Obj_API_FQDN_1",
    "type": "FQDN",
    "value": "downloads.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_FQDN_2",
    "type": "FQDN",
    "value": "support.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  }
]

Note: When creating bulk FQDN objects select Bulk Parameter as True. In a single Bulk Push maximum 1000 entries can be created using POST method.

Create Service Object

Single Service Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST and click Try it Out.

JSON format used to push single service object:

{
  "name": "Obj_API_Telnet_Port",
  "protocol": "TCP",
  "port": 23,
  "type": "ProtocolPortObject"
}

JSON format used to push single service object with range:

{
  "name": "Obj_API_obj1",
  "protocol": "UDP",
  "port": "1025-65535",
  "type": "ProtocolPortObject"
}

Note: When you define port range in JSON format use double quotes for example "port": "1111-1115" otherwise you can encounter error: "description": "Unprocessable Entity - Unexpected character ('-' (code 45)): was expecting comma to separate Object entries at line: 4, column: 17"

Bulk Service Object

Navigate to Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolportobjects > POST and click Try it Out.

JSON format used to push bulk service objects:

[
  {
    "name": "Obj_API_UDP_Port",
    "protocol": "UDP",
    "port": 123,
    "type": "ProtocolPortObject"
  },
  {
    "name": "Obj_API_TCP_Range",
    "protocol": "TCP",
    "port": "1025-65535",
    "type": "ProtocolPortObject"
  }
]

Note: When creating bulk service objects select Bulk Parameter as True. In a single Bulk Push maximum 1000 entries can be created using POST method.

Troubleshoot

• Refer the document for HTTP status code (REST API Basics)
• User credentials cannot be used for both REST API And GUI interfaces simultaneously, and the user is logged out without warning if used for both.
• All REST requests are logged into these two log files on FMC. Search for your URL (ex. .../object/hosts) with the correct operation(If you are looking for error for GET operation, ensure that your log starts something like GET ...object/hosts)

tail -f /var/opt/CSCOpx/MDC/tomcat/logs/stdout.logs  
tail -f /var/opt/CSCOpx/MDC/log/operation/usmsharedsvcs.log