Skip to main content

Cross Connect API Testing

The Cross Connect API enables you to order, manage, and deinstall physical cable connections between equipment in Equinix data centers. This guide provides testing strategies, examples, and best practices for integrating with the Cross Connect API.

Overview​

Cross connects are physical cable connections using coaxial, fiber, or copper cables that connect customer equipment directly to other customer equipment inside Equinix data centers. Since cross connects transmit data point-to-point, they avoid latency and congestion issues of the public Internet.

The Cross Connect API v2 provides three main endpoints:

MethodEndpointDescription
POST/colocations/v2/orders/crossConnectsOrder new cross connects
PATCH/colocations/v2/orders/crossConnects/{orderId}Update existing cross connect order
POST/colocations/v2/orders/crossConnects/deinstallDeinstall existing cross connects

Before testing the Cross Connect API, ensure you have:

  • An Equinix Developer account with cross connect ordering permissions
  • Valid API credentials (client ID and client secret)
  • Access to appropriate data center locations
  • Understanding of API Authentication

Cross Connect Test Workflow​

Start by validating your authentication flow with the Cross Connect API:

# Test authentication for Cross Connect API (Python example)
import requests

auth_url = "https://api.equinix.com/oauth2/v1/token"
auth_payload = {
    "grant_type": "client_credentials",
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>"
}
response = requests.post(auth_url, data=auth_payload)
data = response.json()

if response.status_code != 200:
    raise Exception(f"Authentication failed: {response.status_code} {data}")

access_token = data.get("access_token")
print("Access token:", access_token)
print("Token timeout:", data.get("token_timeout"))

Basic Cross Connect Order Test

Test the most common scenario - ordering a single mode fiber cross connect:

import requests
import json

# Setup authentication
base_url = "https://api.equinix.com"
auth_url = f"{base_url}/oauth2/v1/token"
auth_payload = {
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

auth_response = requests.post(auth_url, data=auth_payload)
token = auth_response.json()["access_token"]

# Prepare request
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Test ordering a basic single mode fiber cross connect
payload = {
    "customerReferenceId": "TEST-CC-001",
    "description": "Test cross connect for API integration",
    "details": [
        {
            "aSide": {
                "connectionService": "SINGLE_MODE_FIBER",
                "mediaType": "SINGLE_MODE_FIBER",
                "protocolType": "10_GIG_ETHERNET",
                "connectorType": "FC",
                "patchPanel": {
                    "id": "CP:0104:1199890"
                }
            },
            "zSide": {
                "patchPanel": {
                    "id": "PP:0104:1190123"
                },
                "circuitId": "TEST-CIRCUIT-001",
                "connectorType": "LC"
            }
        }
    ]
}

response = requests.post(
    f"{base_url}/colocations/v2/orders/crossConnects",
    headers=headers,
    data=json.dumps(payload)
)

# Verify response
assert response.status_code == 201, f"Failed to create order: {response.text}"
order_data = response.json()
order_id = order_data.get("orderId")

print(f"Successfully created Cross Connect order with ID: {order_id}")
print(f"Current status: {order_data.get('status')}")

Best Practices for Cross Connect API Testing​

Use Sandbox Environment

  • Always start testing in the sandbox environment:
# Use sandbox URL for testing
SANDBOX_BASE_URL = "https://sandboxapi.equinix.com"
PRODUCTION_BASE_URL = "https://api.equinix.com"

# Use sandbox for development
base_url = SANDBOX_BASE_URL if os.getenv("ENVIRONMENT") == "sandbox" else PRODUCTION_BASE_URL

Invalid Patch Panel IDs

  • Ensure patch panel IDs follow the correct format: CP:XXXX:XXXXXXX
  • Verify patch panel availability in the target data center

Authentication Errors

  • Check token expiration (typically 1 hour)
  • Verify client credentials are correct
  • Ensure proper OAuth2 flow implementation

Validation Errors

  • Review required vs optional fields in the API specification
  • Check data types and format requirements
  • Validate enum values for connectionService, mediaType, etc.

Permission Errors

  • Verify your account has cross connect ordering permissions
  • Check data center access permissions
  • Ensure you have access to the specified IBX locations

Need Help​

If you encounter issues while testing the Cross Connect API: