Smarthands API Testing
This guide provides specific testing approaches and examples for the Equinix Smarthands API, building on the general API Testing principles.
Smarthands API Overview
The Smarthands API allows you to programmatically request and manage various remote hands services in Equinix IBX data centers.
Here are the ECP API Mapping to the types of supported smarthands types:
Smarthands Testing Workflow
Before testing the Smarthands API, ensure you have:
- Valid API credentials with appropriate permissions
- Access to Equinix IBX locations where you have equipment
- Familiarity with the service ticket workflow
Creating a Smarthands Service Request
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 Smarthands request
base_url = "https://api.equinix.com/v1"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
}
# Example: Create a cage escort request
request_payload = {
"customerReferenceNumber": "RSS41244",
"purchaseOrder": {
"number": "123455",
"purchaseOrderType": "EXISTING"
},
"ibxLocation": {
"ibx": "AM1",
"cages": [
{
"cage": "AM1:01:001MC3",
"accountNumber": "12345",
"cabinets": [
"AM1:01:001MC3:0102"
]
}
]
},
"contacts": [
{
"contactType": "ORDERING",
"userName": "jondoe@test.com"
},
{
"contactType": "NOTIFICATION",
"userName": "jondoe@test.com"
},
{
"contactType": "TECHNICAL",
"name": "John Doe",
"workPhone": "1111111",
"workPhonePrefToCall": "ANYTIME",
"mobilePhone": "1111111",
"mobilePhonePrefToCall": "ANYTIME"
}
],
"schedule": {
"scheduleType": "STANDARD",
"requestedStartDate": "2017-04-05T12:00:00Z",
"requestedCompletionDate": "2017-04-05T12:00:00Z"
},
"attachments": [
{
"id": "eb9ab7e9-3785-41e4-af24-112dff",
"name": "eb9ab7e9-3785-41e4-af24-asfsa5424"
}
],
"serviceDetails": {
"durationVisit": "30 Minutes",
"openCabinetForVisitor": false,
"scopeOfWork": "Scope of work",
"supervisionReqForVisitor": false,
"workVisitOrderNumber": "1-108050984499"
}
}
create_response = requests.post(
f"{base_url}/orders/smarthands/cageEscort",
headers=headers,
data=json.dumps(request_payload)
)
# Verify response
assert create_response.status_code == 201, f"Failed to create request: {create_response.text}"
order_number = create_response.json()["OrderNumber"]
print(f"Successfully created Smarthands request with order number: {order_number}")
Checking Request Status
# Test retrieving request status
status_response = requests.get(
f"https://api.equinix.com/colocations/v2/orders/{order_number}",
headers=headers
)
assert status_response.status_code == 200, f"Failed to retrieve status: {status_response.text}"
status = status_response.json()["status"]
print(f"Current request status: {status}")
Testing Error Scenarios
Always test error handling for your API implementation:
# Test with invalid location
invalid_payload = {
"customerReferenceNumber": "RSS41244",
"purchaseOrder": {
"number": "123455",
"purchaseOrderType": "EXISTING"
},
"ibxLocation": {
"ibx": "INVALID", # Invalid IBX code
"cages": [
{
"cage": "INVALID:01:001MC3",
"accountNumber": "12345",
"cabinets": [
"INVALID:01:001MC3:0102"
]
}
]
},
"contacts": [
{
"contactType": "ORDERING",
"userName": "jondoe@test.com"
}
],
"schedule": {
"scheduleType": "STANDARD",
"requestedStartDate": "2025-08-01T10:00:00Z",
"requestedCompletionDate": "2025-08-01T12:00:00Z"
},
"serviceDetails": {
"durationVisit": "30 Minutes",
"openCabinetForVisitor": false,
"scopeOfWork": "Test invalid IBX location",
"supervisionReqForVisitor": false
}
}
error_response = requests.post(
f"{base_url}/orders/smarthands/cageEscort",
headers=headers,
data=json.dumps(invalid_payload)
)
# Verify error response
assert error_response.status_code == 400, f"Expected error but got: {error_response.status_code}"
assert "Invalid IBX location" in error_response.text, "Error message not as expected"
Best Practices for Smarthands API Testing
Important Note: The Equinix API is a production system that creates real shipment requests. Always follow these testing best practices to ensure you don't create unintended operational work.
- Set up a dedicated testing account: Request a separate account for testing if possible
- Start with read-only operations: Test GET endpoints first before creating/modifying resources
- Use clearly marked test requests: Always prefix descriptions with "TEST:" to help operators identify test requests
- Clean up test resources: Cancel any test shipments immediately after successful creation
- Include Complete Details: Provide comprehensive information in your requests
- Tracking Numbers: Always provide accurate tracking numbers for inbound shipments to ensure proper handling
- Contact Information: Ensure the contact information is current and the person is available during the scheduled service window
- Description Details: Be detailed but concise in describing requirements to help facility staff complete your request efficiently
Automation Considerations
When building automation around the Smarthands API:
- Implement proper error handling and retries
- Consider implementing webhook receivers for status updates
- Build in validation for time windows and service availability
- Include audit logging of all API interactions
- Ensure tracking information is automatically included for all shipment-related requests
- Validate contact availability during scheduled service windows