Skip to main content
Index

V3 APIs Migration

What is ECXF  V3 APIs?

 

Equinix Cloud Exchange Fabric V3 (ECXF V3) was released in February 2018 and is an enhanced version of ECXF APIs with advanced capabilities such as inter-metro connectivity options and dynamic bandwidth changes. As the successor to ECXF V2 APIs, it brings more functionality and capability than previous versions, yet it is simpler to use. Additionally, any new enhancements and features to ECX Fabric capabilities will only be available in V3.

 

Why must you migrate to ECXF V3?

 

ECX Customers should migrate to v3 to take advantage of new capabilities or features released as part of ECX Fabric. After January 5, 2020, Equinix will stop supporting ECXF V2 APIs and after July 5, 2020, all previous versions of ECXF APIs will be retired.

 

What are the unique capabilities of V3 APIs?

 

The table below shows feature capabilities across all three versions of ECX APIs where they differ.

 

Features Description Cloud Exchange (V1) Cloud Exchange (V2) Cloud Exchange Fabric (V3)

Inter-region and Inter-metro connections support

Create connections between metros (ex. Ashburn to Dallas) and between regions (ex. APAC to AMER) No No Yes

Private connectivity (Equinix Any-to-any)

Create connections to any other ECX participant, not just to cloud providers No No Yes

Reseller Model Support

Support for sub-account creation and connection management by a reseller No No

Yes

API support to create connections to Google Cloud Interconnect (GCI)

API integration with GCI to automate a seamless connections creation experience using ECX APIs No No Yes

API support to create connections to IBM DirectLink

API integration with IBM DirectLink to automate a seamless connections creation experience using ECX APIs No No Yes

Bandwidth resizing for Azure, GCI, Oracle and all generic private connections

Ability to adjust the bandwidth of a virtual connection with a single API call in real-time No No Yes

Get all inventory by port name

This option is not available in V3 – see below for connection filtering options Yes Yes No

Enhanced Inventory Retrieval Options

Enhanced GET Connection API to allow more options to connection filtering including:

Get connection by UUID
Get connection by service or authorization key
Get connections by port UUID (show all connections on a particular port)
Get connections by Status (Equinix side status)
Support to show total connections and pagination

No No

Yes

External APIs for Quoting and Pricing

Returns pricing information for connections based on a port, metro and bandwidth No No Yes

Get Port Utilization Stats

Returns port utilization stats for a specified time period No No Yes

Named tags and custom Manual C-tag support*

Support for naming of c-tags No No Yes

Create Connections Support for port to port connections (only specify a-side and z-side port)

Create a connection between two of your own ports quickly and easily without the need to create a service profile No No Yes

Connection deletion confirmation/approval

V3 removes the need for a service provider to approve a deleted connection and immediately deletes the connection and stops billing when this action is performed by a user  Yes Yes No

Set port Threshold

Customers/Partners can set a threshold for committed bandwidth so they will be notified via email when the port reaches a percentage commit (ex. 80%) No Yes Yes

 

 

How complex is this migration?

 

V3 APIs reflect significant changes to the underlying architecture of ECXF. V3 APIs have been completely redesigned and redefined to not only provide additional features but also simplify complexity and improve user experience. Therefore, customers need to plan for a complete upgrade of ECXF APIs to new calls and payloads and will not be able to seamlessly migrate from previous versions of ECXF. We recommend customers consider V3 APIs as a separate API set and re-integrate their use cases based on our API documentation

 

How to redesign ECX V2 API use cases in  ECXF V3 ?

 

ECXF V3 is the successor to ECX V2 APIs. All the core use cases achieved from previous ECXF versions such as connecting to cloud service providers (AWS, Azure etc.), creating service profiles, retrieving connection details and others can still be achieved via V3 APIs. V3 APIs have not removed core use cases but enhanced them to provide better experience and convenience. The following section provides a step by step guide on how to redesign some of the common use cases in V2 using V3 APIs.

 

Usecase 1: Create a layer 2 connection to AWSU

 

Step 1: Retrieve AWS Account ID

 

Step 2: Get user port information  

 

V2 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v2/ports"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "ports": [
        {
            "name": "IP-PORT4",
            "bandwidths": [
                "10 G"
            ],
            "is_buyout": "N",
            "ibx_name": "DC5",
            "layer3": "Y",
            "metro_code": "DC",
            "metro_name": "Ashburn",
            "port_group": "1",
            "port_priority": "Primary",
            "encapsulation": "Dot1q",
            "cross_connect_ids": [
                "20442963"
            ]
        }]
}

 

V3 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v3/port/userport"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

[
    {
        "uuid": "234d-9351-3510-b4e0-30ac094f8af1",
        "name": "TEST-DA-CX-SEC-01",
        "provisionStatus": "ADDED",
        "region": "AMER",
        "device": "225CAD33546A11FCAC5FA288DC",
        "totalBandwidth": 1000000000,
        "accountUcmId": "1000007786",
        "accountName": "EQUINIX",
        "buyout": true,
        "custOrgId": "7033",
        "custOrgName": "EQUINIX",
        "ibx": "DA1",
        "metroCode": "DA",
        "metroDescription": "Dallas",
        "deviceGroup": "2",
        "devicePriority": "Secondary",
        "encapsulation": "Dot1q",
        "viewPortPermission": true,
        "placeVcOrderPermission": true,
        "createdDate": "2017-10-16 21:08:40.0",
        "lastUpdatedDate": "2017-10-16 21:10:30.0",
        "userPorts": [
            {
                "bandwidth": 1000000000,
                "crossConnectId": "2079726",
                "cabinetNumber": "0119",
                "cageNumber": "DA1:01:000280",
                "patchPanelName": "PP:01:1076970",
                "tagProtocolId": "0x8100",
                "portProvisionStatus": "PROVISIONED",
                "patchPanelPorts": "1,2"
            }
        ],
        "layer3Enabled": true,
        "lag": true
    }
  ]

 

Refer to GET ports under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the above V2 API, likewise,  refer to GET userport under Layer 2 Buyer APIs (V3) for more information on how to use its V3 counterpart. 

 

Step 3: Get metro details

 

V2 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v2/metros"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "metros": [
        {
            "name": "Amsterdam",
            "code": "AM"
        },
        {
            "name": "Warsaw",
            "code": "WA"
        },
        {
            "name": "Zurich",
            "code": "ZH"
        }
    ]
}

 

V3 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/common/metros"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
        "name": "Amsterdam",
        "code": "AM",
        "region": "EMEA",
        "cloudReach": [
            "SO",
            "IL",
            "LS",
            "PE",
            "SY",
            "SP"
        ]
}

 

Refer to GET metros under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the above V2 API, likewise, refer to GET metros under Layer 2 Buyer APIs (V3) for more information on how to use its V3 counterpart.

 

Step 4: Get service profile details

 

V2 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v2/sellerservices?metroCode=Sv"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
  "seller_services": [
    {
      "name": "AWS Direct Connect - High Capacity",
      "metros": [
        {
          "availability_status": "In Trail testing",
          "code": "HK",
          "ibxs": [
            "HK2"
          ],
          "name": "Hong Kong"
        }
      ]
    }
  ]
}

 

V3 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles/services?metroCode=Sv"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "isFirstPage": true,
    "isLastPage": false,
    "totalCount": 652,
    "pageSize": 20,
    "content": [
        {
            "uuid": "de55ca94-df3b-4680-845f-6f7093f76bef",
            "name": "AWS Direct Connect - High Capacity",
            "authKeyLabel": "AWS Account ID",
            "connectionNameLabel": "Virtual Circuit Name",
            "requiredRedundancy": false,
            "allowCustomSpeed": false,
            "speedBands": [
                {
                    "speed": 1,
                    "unit": "GB"
                },
                {
                    "speed": 10,
                    "unit": "GB"
                }
            ],
            "description": "You must have AWS Account ID to create Layer 2 connection to Amazon - AWS Direct Connect - High Capacity",
            "createdDate": "2019-06-13T22:58:11.943Z",
            "createdBy": "cxsellercapacity@equinix.com1",
            "lastUpdatedDate": "2020-02-19T21:16:03.910Z",
            "lastUpdatedBy": "cxsellercapacity@equinix.com1",
            "vlanSameAsPrimary": false,
            "tagType": "CTAGED",
            "apiAvailable": true,
            "selfProfile": false,
            "speedFromAPI": false,
            "profileEncapsulation": "Dot1q",
            "globalOrganization": "AWS",
            "organizationName": "EQUINIX-AWS",
            "allowHighAvailability": true,
            "allowAuthorizationKeyReUse": true,
            "allowSecondaryLocation": true,
            "private": false,
            "features": {
                "cloudReach": true,
                "testProfile": false
            }
        }
      ]
}

 

Refer to GET sellerservices under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the above V2 API, likewise, refer to GET services under Layer 2 Buyer APIs (V3) for more information on how to use its V3 counterpart. 

 

Step 5: Post connection request

 

V2 request and response

 

curl -X

POST "https://api.equinix.com/ecx/v2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

   "metro_code": "SV",
   "service_type": "Layer 2 Cloud Service Connectivity",
   "seller_service_name":"AWS Direct Connect",
   "primary_name": "AWS_Demo",
   "primary_port_name": "EQIX-DEMO-SV4-CX-PRI-03",
   "primary_vlan_id": "450",
   "aws_account": "923245056882",
   "primary_speed":"1 GB"

}'

 

{
    "message": "Your Connection request is successful.",
    "result": "SUCCESS",
    "more_info": "",
    "primary_connection_id": "c58484c1-e272-4b3a-b8ad-c7c4515e2d42"
}

 

V3 request and response

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "primaryName": "AWS_Demo_v3",
   "profileUUID": "de2494-df3b-4680-845f-6ff54f76bef",
   "speed":"1" ,
   "speedUnit": "GB",
   "notifications": [
   "johnDoe@equinix.com"
   ],
   "purchaseOrderNumber": "1234",
   "primaryPortUUID": "6f44872-4d2c-d2c0-88e0-30aafd83bb",
   "primaryVlanSTag": "790",
   "sellerRegion": "us-west-1",
   "sellerMetroCode": "SV",
   "authorizationKey": "905236882"
}'

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "3a4ca7d6-3f03-4348-85cd-42f567eaer46"
}

 

Refer to POST connection under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the above V2 API, likewise, refer to Connect to AWS under How-to Guide for more information on how to call its V3 counterpart to establish a connection to AWS.

 

Step 6: Accept connection

 

V2 request and response

 

curl -X

PATCH "https://api.equinix.com/ecx/v2/hostedconnection/connection/c58484c1-e272-4b3a-b8ad-c7c4515e2d42"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "connection_type":"single",
   "access_id":"AKIAERTJXDX6E",
   "secret_key":"Jqya30F8rdxERTDG+d9uEZ0AW/k435Iq"
}'

 

{
    "message": "Connection enabling request successful",
    "result": "SUCCESS",
    "more_info": ""
}

 

V3 request and response

 

curl -X

PATCH "https://api.equinix.com/ecx/v3/l2/connections/3a4ca7d6-3f03-4348-85cd-42f567eaer46?action=Approve"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "accessKey":"AKIERT45DX6E",
"secretKey":"Jqya30F8rdxWERFSTkWIq"
}'

 

{
    "message": "updated connection successfully",
    "primaryConnectionId": "3a4ca7d6-3f03-4348-85cd-42f567eaer46"
}

 

Refer to PATCH connection under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the above V2 API, likewise, refer to Connect to AWS under How-to Guide for more information on how to call its V3 counterpart to accept an AWS connection

 

Usecase 2: Create a layer 2 connection to Azure

 

Step 1: Retrieve Microsoft Service Key

 

Step 2: Get user port information  

 

V2 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v2/ports"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "ports": [
        {
            "name": "IP-PORT4",
            "bandwidths": [
                "10 G"
            ],
            "is_buyout": "N",
            "ibx_name": "DC5",
            "layer3": "Y",
            "metro_code": "DC",
            "metro_name": "Ashburn",
            "port_group": "1",
            "port_priority": "Primary",
            "encapsulation": "Dot1q",
            "cross_connect_ids": [
                "20442963"
            ]
        }]
}

 

V3 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v3/port/userport"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

[
    {
        "uuid": "234d-9351-3510-b4e0-30ac094f8af1",
        "name": "TEST-DA-CX-SEC-01",
        "provisionStatus": "ADDED",
        "region": "AMER",
        "device": "225CAD33546A11FCAC5FA288DC",
        "totalBandwidth": 1000000000,
        "accountUcmId": "1000007786",
        "accountName": "EQUINIX",
        "buyout": true,
        "custOrgId": "7033",
        "custOrgName": "EQUINIX",
        "ibx": "DA1",
        "metroCode": "DA",
        "metroDescription": "Dallas",
        "deviceGroup": "2",
        "devicePriority": "Secondary",
        "encapsulation": "Dot1q",
        "viewPortPermission": true,
        "placeVcOrderPermission": true,
        "createdDate": "2017-10-16 21:08:40.0",
        "lastUpdatedDate": "2017-10-16 21:10:30.0",
        "userPorts": [
            {
                "bandwidth": 1000000000,
                "crossConnectId": "2079726",
                "cabinetNumber": "0119",
                "cageNumber": "DA1:01:000280",
                "patchPanelName": "PP:01:1076970",
                "tagProtocolId": "0x8100",
                "portProvisionStatus": "PROVISIONED",
                "patchPanelPorts": "1,2"
            }
        ],
        "layer3Enabled": true,
        "lag": true
    }
  ]

 

Refer to GET ports under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the aboveV2 API, likewise,  refer to GET userport under Layer 2 Buyer APIs (V3) for more information on how to use its V3 counterpart. 

 

Step 3: Get metro details

 

V2 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v2/metros"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "metros": [
        {
            "name": "Amsterdam",
            "code": "AM"
        },
        {
            "name": "Warsaw",
            "code": "WA"
        },
        {
            "name": "Zurich",
            "code": "ZH"
        }
    ]
}

 

V3 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/common/metros"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
        "name": "Amsterdam",
        "code": "AM",
        "region": "EMEA",
        "cloudReach": [
            "SO",
            "IL",
            "LS",
            "PE",
            "SY",
            "SP"
        ]
}

 

Refer to GET metros under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the aboveV2 API, likewise, refer to GET metros under Layer 2 Buyer APIs (V3) for more information on how to use its V3 counterpart.

 

Step 4: Get service profile details

 

V2 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v2/sellerservices?metroCode=Sv"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
  "seller_services": [
    {
        "name": "SG Azure Express Route",
            "metros": [
                {
                    "availability_status": "In Trail testing",
                    "code": "SG",
                    "ibxs": [
                        "SG1"
                    ],
                    "name": "Singapore"
                }
            ],
            "allow_custom_speed": "N",
            "standard_speeds": [
                "Up to 50MB",
                "Up to 200MB",
                "Up to 500MB",
                "Up to 1000MB",
                "Up to 10MB"
            ],
            "require_redundancy": "N",
            "encapsulation": "Dot1q",
            "service_summary": "L2 connection to Azure Express Route",
            "service_type": "Layer 2 Cloud Service Connectivity",
            "bgp_community_tag": "",
            "req_buyer_ip_prefixes": "",
            "ipsec_nat_traversal_support": ""
        }
        ]
}

 

V3 request and response

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles/services?metroCode=Sv"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "isFirstPage": true,
    "isLastPage": false,
    "totalCount": 652,
    "pageSize": 20,
    "content": [
       
   {
            "uuid": "4c9f7f05-b7d0-4e59-b237-8f7ed902a276",
            "name": "SG Azure Express Route",
            "connectionNameLabel": "Connection",
            "requiredRedundancy": false,
            "allowCustomSpeed": false,
            "speedBands": [
                {
                    "speed": 50,
                    "unit": "MB"
                },
                {
                    "speed": 200,
                    "unit": "MB"
                },
                {
                    "speed": 500,
                    "unit": "MB"
                },
                {
                    "speed": 1000,
                    "unit": "MB"
                },
                {
                    "speed": 10,
                    "unit": "MB"
                }
            ],
            "description": "L2 connection to Azure Express Route",
            "createdDate": "2019-08-21T07:05:44.044Z",
            "createdBy": "pt_aplikanusa",
            "lastUpdatedDate": "2020-02-19T08:30:09.303Z",
            "lastUpdatedBy": "pt_aplikanusa",
            "vlanSameAsPrimary": false,
            "tagType": "CTAGED",
            "apiAvailable": false,
            "selfProfile": false,
            "speedFromAPI": false,
            "profileEncapsulation": "Dot1q",
            "organizationName": "PT APLIKANUSA LINTASARTA",
            "allowHighAvailability": true,
            "allowAuthorizationKeyReUse": true,
            "allowSecondaryLocation": true,
            "private": false,
            "features": {
                "cloudReach": true,
                "testProfile": false
            }
        }
      ]
}

 

Refer to GET sellerservices under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the above V2 API, likewise, refer to GET services under Layer 2 Buyer APIs (V3) for more information on how to use its V3 counterpart.

 

Step 5: Post connection request

 

V2 request and response

 

curl -X

POST "https://api.equinix.com/ecx/v2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "metro_code": "SV",
   "service_type": "Layer 2 Cloud Service Connectivity",
   "seller_service_name":"Azure Express Route",
   "redundancy_type":"Dual Home",
   "primary_name": "Azure_Demo_Primary_V2",
   "primary_port_name": "EQIX-EMERGING-SERVICES-SV4-CX-PRI-03",
   "secondary_name": "Azure_Demo_Secondary_V2",
   "secondary_port_name": "EQIX-EMERGING-SERVICES-SV4-CX-SEC-02",
   "primary_vlan_id": "450",
   "secondary_vlan_id": "451",
   "named_tag": "Public",
   "service_key": "c3c1fc93-6fb0-4b1a-b6ae-83cfa7f63487",
   "primary_speed":"50 MB"
}

 

{
    "message": "Your Connection request is successful.",
    "result": "SUCCESS",
    "more_info": "",
    "primary_connection_id": "a3fa221a-e415-4992-8cac-4981a960f879",
    "secondary_connection_id": "cc6c4783-5308-421b-b2ac-149e4e204907"
}

 

V3 request and response

 

curl -X

POST "https://api.equinix.com/ecx/v3/l2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
   "primaryName": "Azure_Demo_Primary_V3",
   "profileUUID": "a1390b22-bbe0-4e93-ad37-85beef9d254d",
   "speed": 50,
   "speedUnit": "MB",
   "purchaseOrderNumber": "",
   "primaryPortUUID": "8e638dbf-1713-7130-64e0-30ac094f85f6",
   "primaryVlanSTag": "858",
   "secondaryName": "Azure_Demo_Secondary_V3",
   "secondaryVlanSTag": "842",
   "secondaryPortUUID": "8e63964b-ac3e-c3e0-1ae0-30ac094f8edc",
   "namedTag": "Public",
   "sellerMetroCode": "SV",
   "authorizationKey": "c3c1fc93-6fb0-4b1a-b6ae-83cfa7f63487",
   "notifications": [
   "johndemo@equinix.com"
]
}'

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "8d376c78-2949-4da7-ba55-eb29a6d45a73",
    "secondaryConnectionId": "660c50b1-5c90-445c-bef2-93326e81be11"
}

 

Refer to POST connection under the Layer 2 Buyer APIs (V2 - Deprecated) section for more information about the aboveV2 API, likewise, refer to Connect to Azure under How-to Guide for more information on how to call its V3 counterpart to establish a connection to Azure.

 

Step 6: Setup Microsoft peering

 

Configure BGP peering on the Azure portal and wait for Equinix to synchronize the peering settings. Refer to https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-routing-portal-resource-manager for instructions on how to configure peering for an Express Route connection.