Skip to main content

General API Testing

Effective API testing is a critical component of any successful integration with Equinix services. This guide provides best practices, tools, and methodologies to ensure your API implementations are robust and reliable.

Getting Started with API Testing​

This section guides you through setting up your environment for testing Equinix APIs.

Setting up the Test Environment​

Authentication: All Equinix APIs are secured using OAuth2. Before making any API calls, you must obtain an access token. Refer to our API Authentication guide for detailed instructions on how to get your client_id and client_secret and how to use them to generate a token.

Test Data: Some API calls may require existing resources (an organization ID, or a specific port). You may need to create these resources first through the Equinix portal or via the API. Refer to the specific API's documentation for guidance on what data is needed for your test cases.

Roles and Permissions: Your API credentials are tied to a user account and inherit its permissions. Ensure the user account has the necessary roles and permissions to perform the actions you want to test. For example, to create a Fabric connection, you might need "Connection Manager" permissions. These are product-specific and can be managed in the Equinix Customer Portal.

Common Inputs: Before you start testing, gather the following common inputs:

  • API Endpoint URL: The base URL for the service you are testing (e.g., https://api.equinix.com/fabric/v4).
  • Authentication Token: A valid OAuth2 token.
  • Resource Identifiers: UUIDs for any existing resources you will be interacting with (e.g., port_uuid, organization_id).
  • Request Body Payloads: JSON payloads for POST or PUT requests, structured according to the API specification.

Testing Environments​

Equinix provides separate environments to support your development lifecycle:

EnvironmentPurposeBase URL
SandboxDevelopment and initial testinghttps://sandbox-api.equinix.com
ProductionLive environmenthttps://api.equinix.com

Note: Sandbox environment may have limitations on certain operations. Refer to specific API documentation for details.

We recommend the following tools for testing Equinix APIs:

  • Postman: Create and share API collections for manual and automated testing
  • cURL: Command-line tool for quick API interaction
  • Jest/Mocha: JavaScript testing frameworks for automated tests
  • Python Requests: Simple HTTP library for Python-based testing

Testing Workflow​

Validate Authentication

# Short runnable authentication test using requests
import requests

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

print("Status code:", response.status_code)
print("Access token:", data.get("access_token"))
print("Expires in:", data.get("token_timeout"))

Create comprehensive test scenarios that cover complete user journeys:

  • Provision a new service
  • Configure service parameters
  • Query service status
  • Update service configuration
  • Deprovision the service
import requests
import json

# Setup authentication
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"
}

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

# Test creating a connection
base_url = "https://api.equinix.com/fabric/v4"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create connection payload
connection_payload = {
  "type": "EVPL_VC",
  "name": "My-Layer2-Connection-3",
  "bandwidth": 1000,
  "redundancy": {
    "priority": "PRIMARY"
  },
  "aSide": {
    "accessPoint": {
      "type": "COLO",
      "port": {
        "uuid": "a8ba52de-faae-43b5-b0b1-6904d37ee063"
      },
      "linkProtocol": {
        "type": "DOT1Q",
        "vlanTag": 1001
      }
    }
  },
  "order": {
    "purchaseOrderNumber": "po1234"
  },
  "zSide": {
    "accessPoint": {
      "type": "COLO",
      "port": {
        "uuid": "a00cef6f-8e35-4794-9ff9-665e084e4e6d"
      },
      "linkProtocol": {
        "type": "DOT1Q",
        "vlanTag": 1001
      }
    }
  },
  "notifications": [
    {
      "type": "ALL",
      "emails": [
        "test@test.com"
      ]
    }
  ]
}

# Test creating a connection
create_response = requests.post(
    f"{base_url}/connections", 
    headers=headers, 
    data=json.dumps(connection_payload)
)

# Verify response
assert create_response.status_code == 201, f"Failed to create connection: {create_response.text}"
connection_id = create_response.json()["uuid"]

# Test retrieving connection details
get_response = requests.get(
    f"{base_url}/connections/{connection_id}", 
    headers=headers
)

assert get_response.status_code == 200, f"Failed to retrieve connection: {get_response.text}"

Test Error Handling​

Verify that your application correctly handles API errors:

  • Test with invalid parameters
  • Test with incorrect authentication
  • Test with expired tokens
  • Verify error response formats

API Product Testing​

Equinix provides specific testing guides for individual product APIs:

Each guide builds on these general testing principles while providing product-specific examples and best practices.

Need Help?​

If you encounter issues while testing Equinix APIs: