Site Management API Multi-Tool Workshop

Welcome to this hands-on workshop where you'll learn to manage Cato Networks infrastructure (socket sites, network interfaces and network ranges) using three different tools in a real-world workflow. This exercise outlines the API structure for managing site configurations, and demonstrates the flexibility of the Cato API ecosystem, while teaching you when and how to use each tool for maximum efficiency.

What You'll Learn

By the end of this workshop, you'll be able to:

• Install, configure and use the Cato API Explorer (containerized web-based GUI) providing code generation including syntax for python, catocli, and CURL
• Install, configure and use the Cato CLI to both read and update configurations
• Create new Cato sites, network interfaces and add network ranges to interfaces via API

Why Use Multiple Tools?

In real-world scenarios, you'll often use different tools for different tasks:

Prerequisites

Before starting, ensure you have the following installed on your machine:

1. Install Python
2. Install Cato CLI
3. Install Docker Desktop on Mac, Windows, or Linux
   NOTE: Manually start the docker application before checking if it is running
   

   open -a docker

Validate Required Tools

# 1. Docker (for API Explorer) 
docker --version 

# 2. Python 3.6+ 
python3 --version 

# 3. Cato CLI 
catocli --version 

# 4. CURL 
curl --version

Cato API Credentials

You'll need:

1. API Token: Generated from the Cato Management Application. Refer to Generating API Keys for the Cato API.
   NOTE: Save the token securely (you won't be able to view it again).
2. Account ID: Your Cato account number found in Account > Account Info or in the CMA URL, example:
   https://system.cc.catonetworks.com/#/account/{account_id}/

Site Management API Workshop Overview

The site workshop workflow consists of four main phases:

Phase 1: Create Site using Cato API Explorer (Docker Web UI)

Phase 2: Retrieve Site ID using Cato CLI

Phase 3: Update Interface using Cato CLI

Phase 4: Retrieve Interface ID using Cato CLI

Phase 5: Add Network Range using CURL from Cato API Explorer

Phase 1: Create a Site Using API Explorer

Step 1.1: Launch the API Explorer

The Cato API Explorer is a Docker-based web application that provides an interactive GUI for testing GraphQL API calls.

mkdir cato-api-explorer
cd cato-api-explorer

# Create docker-compose.yml
cat << 'EOF' > docker-compose.yml
services:
  cato-api-explorer:
    container_name: cato-api-explorer
    image: ghcr.io/catonetworks/cato-api-explorer:latest
    ports:
    - 8080:8080
    - 8443:443
EOF

# Pull and start the container
docker-compose pull
docker-compose up -d

Step 1.2: Access the API Explorer

# Open in your browser 
open http://localhost:8080

Step 1.3: Configure API Credentials

1. Click on the Settings tab (gear icon)
2. Enter your API Endpoint, API Token, and Account ID
3. Click Save Settings

Step 1.4: Create the Site

Follow these steps in the API Explorer:

1. Navigate to the GraphQL API tab and enter addSocketSite in the API Operation field
2. Select mutation.site.addSocketSite() from the dropdown
3. Click Edit on the addSocketSiteInput field and fill out required fields
4. Change connectionType to SOCKET_X1600, and site name to My 1600 Site
5. Configure the siteLocation with your desired city, state, and country

Request Variables should reflect:

{
    "accountId": "12345",
    "addSocketSiteInput": {
        "connectionType": "SOCKET_X1600",
        "name": "My 1600 Site",
        "nativeNetworkRange": "10.111.0.0/24",
        "siteLocation": {
            "city": "San Diego",
            "countryCode": "US",
            "stateCode": "US-CA",
            "timezone": "America/Los_Angeles"
        },
        "siteType": "BRANCH"
    }
}

Click "Execute" and save the returned siteID.

Example mutation.site.addSocketSite() screenshot in API Explorer:

Phase 2: Retrieve Site ID Using Cato CLI

Now that we've created the site, let's verify it exists and retrieve its ID using the Cato CLI.

Step 2.1: Configure Cato CLI

# Interactive configuration 
catocli configure

Step 2.2: Search for the Site

# Use help menus 
catocli -h catocli entity -h 

# Search by site name 
catocli entity site list -s "My 1600 Site" 

# Pretty print JSON output 
catocli entity site -p 

# Format as CSV 
catocli entity site -s "My 1600 Site" -f csv

Phase 3: Update Interface Using Cato CLI

Now we'll update the site's network interface configuration using syntax generated from the API Explorer.

Step 3.1: List Existing Interfaces

By default when creating a Cato site, the site will have one LAN interface and one WAN interface. The default LAN interface will be configured as the native range used when creating the site.

# Use entityLookup to get interface info 
catocli query entityLookup '{ "entityInput": { "id": "12345", "type": "site" }, "type": "networkInterface" }'

Step 3.2: Update the Interface

In the API Explorer, configure the interface update:

1. Navigate to GraphQL API tab and enter updateSocketInterface
2. Select INT_7 as the interface to configure
3. Set destType to LAN
4. Configure subnet and localIp

Request Variables should reflect:

{
    "accountId": "12345",
    "siteId": "172807",
    "socketInterfaceId": "INT_7",
    "updateSocketInterfaceInput": {
        "destType": "LAN",
        "lan": {
            "localIp": "10.112.0.1",
            "subnet": "10.112.0.0/24"
        }
    }
}

Example mutation.site.() screenshot in API Explorer:

Step 3.3: Execute with Cato CLI

Copy the Cato CLI syntax from the API Explorer and execute using your siteID:

catocli mutation site updateSocketInterface '{ "siteId": "12345", "socketInterfaceId": "INT_7", "updateSocketInterfaceInput": { "destType": "LAN", "lan": { "localIp": "10.112.0.1", "subnet": "10.112.0.0/24" } } }'

Phase 4: Retrieve Interface ID

After updating the interface, retrieve the Interface Entity ID for adding network ranges:

# Retrieve interface details 
catocli entity networkInterface list -f csv 

# Or use entityLookup 
catocli query entityLookup '{ "entityInput": {"id": "12345", "type": "site"}, "type": "networkInterface" }'

Save the Interface Entity ID for the INT_7 interface for use in Phase 5

Phase 5: Add Network Range Using cURL

Finally, we'll add a network range to the INT_7 interface using a raw cURL command.

Step 5.1: Configure in API Explorer

1. In API Explorer, navigate to addNetworkRange
2. Select the LAN_7 interface
3. Configure network range parameters (name, subnet, VLAN, DHCP)
4. Uncheck Mask secret key checkbox to reveal your API key

Example mutation.site.() screenshot in API Explorer:

Step 5.2: Execute cURL Command

Copy the cURL command from the API Explorer and execute in your terminal:

curl -k -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-API-Key: YOUR_API_KEY_HERE" \
  'https://api.catonetworks.com/api/v1/graphql2' \
  --data '{
    "query": "mutation siteAddNetworkRange ( $lanSocketInterfaceId:ID! $addNetworkRangeInput:AddNetworkRangeInput! $accountId:ID! ) { site ( accountId:$accountId ) { addNetworkRange ( lanSocketInterfaceId:$lanSocketInterfaceId input:$addNetworkRangeInput ) { networkRangeId } } }",
    "variables": {
      "accountId": "11362",
      "addNetworkRangeInput": {
        "dhcpSettings": {
          "dhcpType": "ACCOUNT_DEFAULT"
        },
        "localIp": "10.113.0.1",
        "name": "Custom Network",
        "rangeType": "VLAN",
        "subnet": "10.113.0.0/24",
        "vlan": 123
      },
      "lanSocketInterfaceId": "207469"
    },
    "operationName": "siteAddNetworkRange"
  }'

Expected Response: Network Range ID returned

{
    "data": {
        "site": {
            "addNetworkRange": {
                "networkRangeId": "UzY1NDI4Mg=="
            }
        }
    }
}

Key Takeaways

When to Use Each Tool

API Explorer (Web GUI):

• Initial testing and exploration
• Learning the API structure
• One-off changes during troubleshooting
• Generating cURL and Python templates

Cato CLI (catocli):

• Bulk operations and reporting
• Automation scripts
• Quick queries from command line
• CSV/JSON export capabilities
  

cURL (Raw API):

• Troubleshooting and calling APIs directly
• Minimal dependencies
• Custom error handling with verbose output (-v flag)
• Integration examples for any programming language

Additional Resources

• Cato API Essentials - Videos
• Cato CLI
• Cato API Documentation

Congratulations on Completing the Workshop!

You now have hands-on experience with three powerful API tools