api-support@equinix.com
  Sign In   Contact Us
  1. Home
  2. Documentation
  3. Equinix Cloud Exchange Fabric
For Public Viewing
body: 

Legend        Don't like reading - How about a 1-minute video?       Ask us

 

What is Equinix Cloud Exchange Fabric?

Equinix Cloud Exchange Fabric (ECXF) is an advanced software-defined interconnection solution that enables you to directly, securely and dynamically connect to distributed infrastructure and digital ecosystems on platform Equinix via a single port.

 

Customers can use ECXF to connect to:

  • Cloud Service Providers - Clouds, network and other service providers.
  • Enterprises - Other Equinix customers, vendors and partners
  • Myself - Another customer instance deployed at Equinix.

 

ECXF is offered to customers through Equinix Cloud Exchange Fabric web portal and REST APIs.

 

 


body: 

What are Equinix Cloud Exchange Fabric APIs?

The Equinix Cloud Exchange Fabric APIs are a collection of REST APIs that allow you to programmatically order, create, delete and monitor private virtual connections on the ECX Fabric. (Refer API reference section or Catalog for more details.)

 


body: 

How do the Equinix Cloud Exchange Fabric APIs work?

Background

When a client is on-boarded, they are provided with user credentials. 

The client must use these credentials to connect to the Equinix Developer Portal to generate a Consumer key and Consumer secret. 

The Consumer key and Consumer secret are essential for obtaining access and refresh tokens to authenticate API calls as described in the subsequent section.

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to generate Consumer key and Consumer secret.

 

ECXF Cloud Service Provider Workflow

 

 

Step 1  - Retrieve connection credentials from the cloud service provider. For example, Account ID for AWS, Service key for Azure etc.

 

Refer 

AWS console https://docs.aws.amazon.com/directconnect/latest/UserGuide/getting_started.html

Azure portal https://azure.microsoft.com

Google console https://console.cloud.google.com/getting-started 

Oracle console https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/manage-and-monitor-services.html

 

Authorization flow:

Step 2  - Request access and refresh token information by calling the Equinix OAuth API (/oauth2/v1/token) with the Consumer key, Consumer secret, and user credentials. 

 

Refer to Requesting Access and Refresh tokens under the Getting Started for instructions on how to obtain an Authorization Token.

 

Step 3  - The API gateway makes an OAuth2 call to the identity provider using the submitted credentials.

 

Step 4  - The identity provider returns an OAuth2Access token to the API gateway.

 

Step 5  - The API gateway sends back the authorization token details to the client.

 

API Request flow:

Step 6  - The client submits an API request with the obtained authorization token and respective API request payload.

Refer to the How-to Guide section for instructions on how to call Equinix Cloud Exchange Fabric APIs to establish connections.

 

Step 7  - API gateway validates the request and calls the relevant API.

 

Step 8  - The response is received by the API gateway.

 

Step 9  - The response is sent back to the client.

 

Step 10  - Client acknowledges connection using the console provided by the respective cloud service provider (a) or via Equinix Cloud Exchange Fabric portal (b) or APIs (c). 

 

Refer 

AWS console https://docs.aws.amazon.com/directconnect/latest/UserGuide/getting_started.html

Azure portal https://azure.microsoft.com

Google console https://console.cloud.google.com/getting-started 

Oracle console https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/manage-and-monitor-services.html

 

Equinix Cloud Exchange Fabric portal https://ecxfabric-documentation.equinix.com/hc/en-us/articles/360004956811

 

Refer to the How-to Guide section for instructions on how to accept connections using Equinix Cloud Exchange Fabric APIs.

 


body: 

How-to Guide for ECX Fabric use cases

Learn how to create a variety of connections using ECX Fabric APIs!

 

 

 


body: 

Pre-requisites

  • You have valid user credentials.
  • You have been authorized to access the developer portal.
  • You have been authorized to create, modify and delete connections by your master Admin.

 


body: 

Getting Started

Learn the fundamentals of Equinix Cloud Exchange Fabric APIs.

 


body: 

Generating Client ID and Client Secret key

To obtain your client ID and client secret key, you must register your app in the developer portal.

1. Login to Equinix Developer Platform using your login credentials.

 

If you are unaware of your login credentials for Equinix Developer Platform, contact your local Equinix Service Desk. 

 

2. After logging in, click on the My Apps section as shown below.

 

 

3. Click on the Add a new App button.

 

 

4. You will need to name your app and then select the API it will use. Once you’re ready you complete the registration with the Create App button.

 

 

5. You should now have your app listed in the My Apps section as shown below:

 

 

6. When you select the application, your Client ID ( Consumer Key) and Client Secret (Consumer Secret) will be revealed.

 

 


body: 

Requesting Access and Refresh tokens

Access Token Flow

The access token is used to exchange data with the Equinix APIs and the refresh token is used to request a new access token should the access token expire. You must submit your user credentials, Client ID, and Client Secret for OAuth 2 authentication to obtain access and refresh tokens as shown in the sample curl command below.

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/token'

-H "content-type: application/json"

-d '{

"grant_type": "password",

"user_name": "john.doe@example.com",

"user_password": "jd1@#$",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

The description of the request headers are as follows:

 

Header Name Mandatory Type Example Applicable Values Description
grant_type Yes string password "password" Different ways to authorize access to resources. It indicates the type of grant to be presented in exchange for an access token.
user_name Yes string john.doe@example.com   The ECXF login username. 
user_password Yes string jd1@#$   The ECXF login password. 
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Portal.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer portal.

 

Refer to Generating a Client ID and Client Secret key under the Getting Started section for instructions on how to create a client ID and client secret.

 

If you are unaware of your user credentials for the Equinix Developer Platform, contact your local Equinix Service Desk. 

 

Once authenticated, an access token, refresh token, and timeout details will be sent to you as shown in the sample JSON response below.

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "zxcvbn1JKLMNOPQRSTU",

    "refresh_token_timeout": "5184000"

}

 

The description of the response payload is as follows:

 

Field Name Type Example Applicable Values Description
access_token string qwErtY8zyW1abcdefGHI   The authorization token to be used in subsequent API calls. 
token_timeout string 3600   The lifetime of an access token in seconds. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
user_name string john.doe@example.com   The ECXF login username.
token_type string Bearer

"Bearer"

"Refresh"

 The type of token. The options available are “Bearer” and “Refresh”.
refresh_token string zxcvbn1JKLMNOPQRSTU   Access tokens have limited lifetimes. If your application needs access to an ECX-F API beyond the lifetime of a single access token, you can obtain a refresh token. A refresh token allows your application to obtain new access tokens.
refresh_token_timeout string 5184000   The lifetime of a refresh token in seconds. For example, the value "5184000" denotes that the refresh token will expire in 60 days from the time the response was generated.

 

To make a request to Equinix APIs, add the Authorization header to the HTTP request with the word "Bearer" prepended to the access token. For example with curl use,  -H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 

Refresh Token Flow

You can use a valid refresh token to obtain new access tokens to be used in API calls. A refresh token is valid for 60 days. You must submit your Client ID, Client Secret and Refresh Token to obtain refresh access tokens as shown in the sample curl command below.

 

curl -X

POST 'https://api.equinix.com/oauth2/v1/refreshaccesstoken'

-H "content-type: application/json"

-d '{

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890",

"refresh_token": "zxcvbn1JKLMNOPQRSTU"

}'

 

The description of the body parameters are as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Portal.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer portal.
refresh_token Yes string zxcvbn1JKLMNOPQRSTU   A refresh token allows your application to obtain a new access token and is provided in the response payload of an access token call.

 

Once requested, a new set of access token, refresh token, and timeout details will be sent to you.

 

{

    "access_token": "1abcdefGHIqwErtY8zyW",

    "token_timeout": "3600",

    "user_name": "john.doe@example.com",

    "token_type": "Bearer",

    "refresh_token": "1JKLMNOPQRSTUzxcvbn",

    "refresh_token_timeout": "5184000"

}

 


body: 

Connect to Cloud Service Providers


body: 

Connect to AWS

End users can create connections to AWS Direct Connect using either a Dot1q port or a QinQ port. When a connection is created, the connection transitions through various states within the Equinix and AWS infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in AWS.

 

Equinix States under /ecx/v3/l2/connections/{connId} AWS States
"status" attribute values "providerStatus" attribute values AWS Direct Connect State Description
PROVISIONING NOT_AVAILABLE   Connection request has not been yet sent to AWS.
PROVISIONED PENDING_APPROVAL 

Ordering -> Requested 

The connection awaits for acceptance.

 

You will see a card stating “Accept Hosted Connection”  on your ECXF - Portal dashboard.
PROVISIONED PROVISIONING Pending Connection establishment in progress.
PROVISIONED PROVISIONED Pending -> Available The connection has been accepted by the client.

 

Refer https://docs.aws.amazon.com/directconnect/latest/APIReference/API_Connection.html for the different AWS connection states.  

 

Click here to watch a video on how to connect to AWS using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 connection to AWS Direct Connect?
 

 


body: 
Step 1: Retrieve AWS Account Info

Locate your AWS account ID using the AWS Management console.

 

The AWS Account ID is a 12 - digit number and is essential for creating an AWS Direct Connect connection.

 

Refer https://docs.aws.amazon.com/directconnect/latest/UserGuide/getting_started.html#get-started-signup for instructions on how to signup for AWS. 

 


body: 
Step 2: Create Connection

2a) Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 

2b) Get Port

Retrieve your allocated ECXF port information.

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2c) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection. (A-side)

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established between your AWS Account Info and the seller profile selected earlier.

 

Refer to Get validateAuthorizationKey under the API Reference section for instructions on how to validate your authorization key. You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.

 

2f) Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show a sample curl request to create a layer 2 AWS connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

AWS Connection using a Dot1q port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "primaryName": "JohnDoe_AWS_Dot1q",
  "profileUUID": "3214888b-39b0-49ea-a232-005088dc9c84",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "774",
  "sellerRegion": "us-west-1",
  "sellerMetroCode": "SV",
  "authorizationKey": "123456789012"
}'

 

AWS Connection using a QinQ port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "primaryName": "JohnDoe_AWS_QinQ",
  "profileUUID": "999552b-39b0-49ea-a232-005088dc9c84",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "0987654321",
  "primaryPortUUID": "99991d3b-9750-7500-bae0-30ac1885197a",
  "primaryVlanSTag": "774",
  "primaryVlanCTag": "775",
  "sellerRegion": "us-west-1",
  "sellerMetroCode": "SV",
  "authorizationKey": "123456789012"
}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
primaryName Yes string JohnDoe_AWS_QinQ   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 99991d3b-9750-7500-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

2 - 4094

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes integer 775

2 - 4094

 C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique identifier of the provider's service profile.
authorizationKey Yes string 123456789012   Authorization Key obtained from the provider. Example: Account ID from AWS.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB MB Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerRegion Yes string us-west-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to AWS (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) S-tag required C-tag required Port Type ( Z-side)
Dot1q port Yes No Dot1q port
QinQ port Yes Yes Dot1q port

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID  of the connection that was just created.

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 


body: 
Step 3: Accept Connection

Accept the virtual connection using AWS Management Console, Equinix Cloud Exchange Portal, or the below API.

 

Patch Connections

PATCH l2/connections/{connid}
 Method  PATCH
 URL or End Point  /ecx/v3/l2/connections/{connId}
 Headers  Authorization, Content-Type
 Query Parameters  action
 Body Parameters  AWS Access Keys (Access Key ID and Secret Access Key)

 

ConnId is an identifier unique for each connection.

 

The PATCH connections API accepts or rejects an L2 connection for a given connection connID.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to accept an L2 connection and its respective JSON response. 

 

curl -X

PATCH "https://api.equinix.com/ecx/v3/l2/connections/9999a8-0e07-44d0-944c-88a25d8d28f7?action=Approve"

-H "content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

"accesskey":"AKIAGGJKJU7BC3QJKYQ",

"secretkey":"CXGJW1lWbqENEqSkBAK"

}'

 

The description of the query and request payload is as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
action Yes string Approve

"Approve"

"Reject"

 The action to perform on the connection.
connId Yes string 9999a8-0e07-44d0-944c-88a25d8d28f7   The unique identifier of the connection.

 

Body Parameter Name Mandatory Type Example Description
accesskey Yes string AKIAGGJKJU7BC3QJKYQ Special keys provided by AWS to authenticate API requests.
secretkey Yes string CXGJW1lWbqENEqSkBAK Special keys provided by AWS to authenticate API requests.

 

{
    "message": "updated connection successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string updated connection successfully Indicates the status of the PATCH API call.
primaryConnectionID string primaryConnectionId: "9999a8-0e07-44d0-944c-88a25d8d28f7" Indicates the primary connection ID of the connection that was accepted.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Refer

https://docs.aws.amazon.com/directconnect/latest/UserGuide/getting_started.html for instructions on how to accept the connection using the AWS console.

https://ecxfabric-documentation.equinix.com/hc/en-us for instructions on how to accept the connection using the Equinix Cloud Exchange Fabric Portal.

 


body: 

Connect to Azure

End users can create connections to Azure Express Route using either a Dot1q port or a QinQ port. When a connection is created, the connection transitions through various states within the Equinix and Azure infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Azure.

 

Equinix States under /ecx/v3/l2/connections/{connId}  Azure States  
"status" attribute values "providerStatus" attribute values Azure's Provider Status Azure's Peerings Status Description
1. PROVISIONING NOT_AVAILABLE Not provisioned Not provisioned   Connection request has not been yet sent to Microsoft Azure.
2. PENDING_BGP_PEERING PENDING_BGP Provisioned Not provisioned The connection has been approved and awaits for the customer to configure Microsoft peering on the Azure portal.
3. PROVISIONING or  PROVISIONED PROVISIONED Provisioned Provisioned Provisioning completed with Microsoft Azure

 

Note that the status will be “Pending BGP Peering” until peering is completed in the Azure portal and the status will only change to "Provisioned" once ECX Fabric syncs with Microsoft. 

If you want to synchronize the BGP peering instantly, you may use the Equinix Fabric Exchange portal.

 

Refer https://docs.aws.amazon.com/directconnect/latest/APIReference/API_Connection.html for the different AWS connection states.  

 

Click here to watch a video on how to connect to Azure using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 connection to Azure ExpressRoute?

 

 


body: 
Step 1: Retrieve Microsoft Service Key

Obtain a location-specific service key via the Azure portal.

 

Refer to https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-circuit-portal-resource-manager for instructions on how to create a connection. 

 


body: 
Step 2: Create Connection

2a) Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key section under the Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens section for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk. 

 

2b) Get Port

Retrieve your allocated ECXF port information.

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2c) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection. (A-side)

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established with your Azure service key and the seller profile selected in the previous step.

 

Refer to Get validateAuthorizationKey under the API Reference section for instructions on how to validate your authorization key. You may skip this step if you are certain that your key is authorized for creating connections with the desired service profile.

 

2f) Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerMetroCode, secondaryName, secondaryPortUUID, secondaryVlanSTag, secondaryVlanCTag, namedTag, primaryZSideVlanCTag, secondaryZSideVlanCTag,

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to create a layer 2 Azure connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

Azure Connection using a Dot1q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1q_Private",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "TestS110",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]

}'

 

C Tag is not applicable for "Private",  "Public"  and "Microsoft" peering.

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1q_Manual",

  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",

  "speed": 50,

  "speedUnit": "MB",

  "purchaseOrderNumber": "",

  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "458",

  "secondaryName": "TestS110",

  "secondaryVlanSTag": "442",

  "secondaryZSideVlanCTag": "542",

  "primaryZSideVlanCTag":"558",

  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",

  "namedTag": "Manual",

  "sellerMetroCode": "SV",

  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",

    "notifications": [

    "JohnDoe@equinix.com"

  ]

}'

 

Azure Connection using a QinQ port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "purchaseOrderNumber": "1234567890",

  "primaryName": "JohnDoe_Azure_QinQ",
  "secondaryName": "JohnDoe2_Azure_QinQ",
  "primaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",
  "secondaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",
  "primaryVlanSTag": 640,
  "secondaryVlanSTag": 650,
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "authorizationKey": "e03da869-8243-4dac-ae49-a95c80f5425d",
  "sellerMetroCode": "DC",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
primaryName Yes string JohnDoe_Dot1q_Manual   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 640

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 84c6616c-573a-447d-a478-9fab8fff284d   Unique identifier of the provider's service profile.
authorizationKey Yes string e03da869-8243-4dac-ae49-a95c80f5425d   Authorization Key obtained from the provider. Example: Service Key from Azure Express Route.
speed Yes integer 50  

Speed/Bandwidth you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string     An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
secondaryName Yes string JohnDoe2_Azure_QinQ   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer secondary port from which the connection would get originate.
secondaryZSideVlanSTag Yes integer 442   S-Tag/Outer-Tag of the secondary connection - A numeric character ranging from 2 to 4094.
secondaryZSideVlanCTag Yes integer 542   C-Tag/Inner-Tag of the secondary connection - A numeric character ranging from 2 to 4094.
namedTag Yes string Private

"Private" 

"Public" 

"Microsoft" 

"Manual"

 The type of peering you would like to set up with Azure Express Route.
primaryZSideVlanCTag Yes integer 558   C-Tag/Inner-Tag of the primary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")
secondaryZSideVlanCTag Yes integer 542   C-Tag/Inner-Tag of the secondary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")

 

ECX Participants with Dot1q ports can create up to three connections to Azure using the same Azure service key. However, all 3 connections must have different namedTags such as "private", "public", "Microsoft" or "Manual"  peering. Note that "Microsoft" peering requires special permission from Microsoft. ECX participants with QinQ ports only need to create one primary and one redundant connection. When creating a connection to Azure, the payload expectations with regard to c-tags and s-tags vary based on the type of port (Dot1q or QinQ) from which you are creating a connection to Azure. The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to Azure Express Route (Z - side QinQ). 

 

Port Type (A-side) Maximum Number Of Connections

Peering Type (indicated by namedTag field)

 S-tag required C-tag required Port Type (Z-side)
Dot1q port 3  pairs (3 primary and 3 redundant) Public Yes No (only Z side C-tag is required and it is provided under VLANID while setting up peering in Azure portal.) QinQ port
Private Yes No (only Z side C-tag is required and it is provided under VLANID while setting up peering in Azure portal.)
Microsoft Yes No (only Z side C-tag is required and it is provided under VLANID while setting up peering in Azure portal.)
Manual Yes Yes (only Z side C-tag is required and it is provided in the ECX portal or in the API request payload.)
QinQ port 1  pair (1 primary and 1 redundant) Public Yes No
Private Yes No
Microsoft Yes No
Manual Yes No

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9994b8d-dcdb-45bc-b760-55368e16f3c4",
    "secondaryConnectionId": "888d4c1-5444-4511-b2e4-51f06f062974"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionId string 9994b8d-dcdb-45bc-b760-55368e16f3c4 Indicates the primary connection ID of the connection that was just created.
secondaryConnectionId string 888d4c1-5444-4511-b2e4-51f06f062974 Indicates the secondary connection ID of the connection that was just created.

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 


body: 
Step 3: Setup Microsoft Peering

Configure BGP peering on the Azure portal and wait for Equinix to synchronize the peering settings. Alternatively, you can also synchronize the peering using the ECXF portal. Once it is completed, the connection status retrieved via the Connections API should change from “Pending-BGP-Peering” to “Provisioned”

 

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. 

 


body: 

Connect to Google

End users can create connections to Google GCP  using either a Dot1q port or a QinQ port. When a connection is created, the connection transitions through various states within the Equinix and Google infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Google.

 

Equinix States under /ecx/v3/l2/connections/{connId} Google States
"status" attribute values "providerStatus" attribute values Google GCP State Description
PROVISIONING NOT_AVAILABLE   Connection request has not been yet sent to Google.
PROVISIONED NOT_AVAILABLE - > PROVISIONING

Waiting for service provider

The connection awaits for acceptance.
PROVISIONED PENDING_APPROVAL - > PROVISIONING Activation needed -> BGP Configuration needed Connection establishment in progress.
PROVISIONED PROVISIONED Pending -> Available The connection has been accepted by the client.

 

Refer https://cloud.google.com/interconnect/docs/concepts/dedicated-overview for the different GCP connection states.  

 

Click here to watch a video on how to connect to GCP using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 connection to Google Cloud Platform?
 

 


body: 
Step 1: Retrieve Google Pairing Key

Obtain your Google pairing key using the Google GCP portal.

 

The Google pairing key is a unique key essential for creating a Google GCP connection. For example, 2dfcdee7-b6f9-41d0-b98f-639151097693/us-west1/1. It comprises of three parts:

1. An alphanumeric key (2cfcdcc7-b6f9-41d0-b98f-639151099393)

2. Region (us-west1) 

3. Zone (1)

 

Ensure to connect to the region and zone indicated in your pairing key when creating a connection. For example, the above pairing key will only work for zone 1 connections.

 

Refer https://cloud.google.com/free/docs/gcp for instructions on how to signup for GCP. 

 


body: 
Step 2: Create Connection

2a) Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 

2b) Get Port

Retrieve your allocated ECXF port information.

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2c) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection. (A-side)

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established between your Google pairing key and the seller profile zone selected earlier.

 

Refer to Get validateAuthorizationKey under the API Reference section for instructions on how to validate your authorization key. You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.

 

2f) Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show a sample curl request to create a layer 2 GCP connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

GCP Connection using a Dot1q port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoeGCPDot1q",

  "profileUUID": "9e441721-5342-4d8a-b62e-5ca61b4aa795",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "456456",

  "primaryPortUUID": "7f891d3b-973c-73c0-bae0-30ac1885197a",

  "primaryVlanSTag": "775",

  "sellerRegion": "us-west1",

  "sellerMetroCode": "SV",

  "authorizationKey": "33835adc-00fd-4fe1-b9f3-78248e126ef7/us-west1/1"

}'

 

GCP Connection using a QinQ port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoeGCPZone2QinQ",

  "profileUUID": "c96a3e82-beb3-40a5-830a-fa75a9d6f08a",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com@equinix.com"

  ],

  "purchaseOrderNumber": "456456",

  "primaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",

  "primaryVlanSTag": "371",

  "primaryVlanCTag": "271",

  "sellerRegion": "us-west1",

  "sellerMetroCode": "SV",

  "authorizationKey": "389730d5-4280-4714-9e8e-216d942a6d3b/us-west1/2"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_GCP_QinQ   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 99991d3b-9750-7500-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes string 775

 

 C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique identifier of the provider's service profile.
authorizationKey Yes string c13d9edf-ee52-42b0-gf3y-889a7a65fe9e/us-west1/2
 		  

Authorization Key obtained from Google. It also indicates the destination zone and region of the connection.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerRegion Yes string us-west-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to Google (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) S-tag required C-tag required Port Type ( Z-side)
Dot1q port Yes No Dot1q port
QinQ port Yes Yes Dot1q port

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "7777a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 7777a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.
 

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 


body: 
Step 3: Activate Connection

Activate the virtual connection using Google Cloud Portal.

 

Refer to https://cloud.google.com/free/docs/gcp for instructions on how to activate the connection using Google Cloud Platform Console.

 


body: 

Connect to Oracle

End users can create connections to Oracle FastConnect using either a Dot1q port or a QinQ port. When a connection is created, the connection transitions through various states within the Equinix and Oracle infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status in Oracle.

 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PROVISIONING NOT_AVAILABLE Connection request has not been yet sent to Oracle.
PROVISIONED PROVISIONING

The connection awaits for acceptance.
PROVISIONED PROVISIONED Connection establishment in progress.

 

Click here to watch a video on how to connect to Oracle FastConnect using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 connection to Oracle FastConnect?

 


body: 
Step 1: Retrieve Oracle OCID

Obtain your Oracle OCID using the Oracle portal.

 

The OCID is a unique key essential for creating an Oracle FastConnect connection. 

 

Refer to https://docs.cloud.oracle.com/iaas/Content/Network/Concepts/fastconnectprovider.htm for instructions on how to signup for Oracle FastConnect. 

 


body: 
Step 2: Create Connection

2a) Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 

2b) Get Port

Retrieve your allocated ECXF port information.

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2c) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection. (A-side)

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2d) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether a connection can be established between your Oracle OCID and the seller profile selected earlier.

 

Refer to Get validateAuthorizationKey under the API Reference section for instructions on how to validate your authorization key. You may skip this step if you are certain that your key is authorized for creating connections with the selected service profile.

 

2f) Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show a sample curl request to create a layer 2 Oracle connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

Oracle Connection using a Dot1q port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "primaryName": "JohnDoeOracleDot1q",
  "profileUUID": "d7f5769b-9618-4d8e-b7dc-9e68ffd0a8b8",
  "speed": 1,
  "speedUnit": "GB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "456299",
  "primaryPortUUID": "9f891d3b-973c-73c0-bae0-30ac1885197a",
  "primaryVlanSTag": "786",
  "sellerRegion": "us-ashburn-1",
  "sellerMetroCode": "DC",
  "authorizationKey": "ocid1.virtualcircuit.oc1.iad.aaaaaaaafzx4jybgymnyfjfwyxl7f4b6emvp3uast2opcf6z7xzp2lqcnpjq"
}'

 

Oracle Connection using a QinQ port

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "primaryName": "JohnDoeOracleQinQ",
  "profileUUID": "c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8",
  "speed": 1,
  "speedUnit": "GB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1111",
  "primaryPortUUID": "7f891e3b-974f-74f0-bae0-30ec1885143a",
  "primaryVlanSTag": "3273",
  "primaryVlanCTag": "1111",
  "sellerRegion": "us-ashburn-1",
  "sellerMetroCode": "DC",
  "authorizationKey": "ocid1.virtualcircuit.oc1.iad.aaaaabcdp2mwua7njveex3vmhchwqwyzzka5zrrhbo4wc7uz46pzlqghkzgq"
}'

 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoeOracleDot1q   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 99991d3b-9750-7500-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes string 775

 

 C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 999552b-39b0-49ea-a232005088dc9c86   Unique identifier of the provider's service profile.
authorizationKey Yes string ocid1.virtualcircuit.oc1.iad.aaafsderteyrty23556  

OCID obtained from Oracle Cloud Infrastructure.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerRegion Yes string us-ashburn-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to Oracle (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) S-tag required C-tag required Port Type ( Z-side)
Dot1q port Yes No Dot1q port
QinQ port Yes Yes Dot1q port

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "567a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 567a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 


body: 

Connect to Enterprises

End users can create connections to other Equinix customers (customers, vendors, and partners) using either a Dot1Q port or a QinQ port. 

 

Click here to watch a video on how to connect to other Equinix customers using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish an L2 non-redundant enterprise connection?

 

 


body: 
Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get Attribute Information

2a) Get Port

Retrieve your allocated ECXF port information.

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2b) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection.

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2c) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

If you intend to create a connection to a private seller service profile, ensure that you have been authorized by the respective seller profile to access and retrieve the service profile details.

In order to do this, the seller must whitelist your email ID  by adding the email address to the private profile in the ECX portal.

For more information please refer to the ECX Fabric documentation at https://ecxfabric-documentation.equinix.com/hc/en-us/articles/360013214112-Setting-your-company-s-visibility

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 


body: 
Step 3: Create Connection

Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerMetroCode, primaryZSideVlanCTag

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create layer 2 non-redundant enterprise connection using  Dot1q and QinQ ports and a sample JSON response for this API. 

 

Non-Redundant Connection from a Dot1q port to a service profile with a Dot1q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_Dot1Q",

  "profileUUID": "8e79b5e4-7c5b-4201-9334-fd89b37bec47",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "4f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "672",

  "sellerMetroCode": "DA"

}

 

Non-Redundant Connection from a Dot1q port to a service profile with a  QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_QinQ",

  "profileUUID": "31b7263f-7e6a-42d0-859e-80a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "335",

  "sellerMetroCode": "SV",

  "primaryZSideVlanCTag": "211",

}

 

Non-Redundant Connection from a QinQ port to a service profile with a Dot1q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_QinQ_To_Dot1Q",

  "profileUUID": "2a73af1a-3c74-47ac-b778-6bf455d1174e",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "6f891d3b-972d-73d0-bae3-30ac1995197a",

  "primaryVlanSTag": "470",

  "primaryVlanCTag": "470",

  "sellerMetroCode": "DA"

}

 

Non-Redundant Connection from a QinQ port to a service profile with a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

{

  "primaryName": "JohnDoe_QinQ_To_QinQ",

  "profileUUID": "32b7273f-7e7a-43d0-859e-81a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-96d3-6d30-bae0-30ac1885197a",

  "primaryVlanSTag": "470",

  "sellerMetroCode": "DA"

}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_AWS_QinQ   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 99991d3b-9750-7500-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes string 775

 

 C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique identifier of the provider's service profile.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to a seller/service profile (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) Vlan S-tag required Valan C-tag required ZSide Vlan C-tag required Port Type ( Z-side)
Dot1Q port Yes No Yes QinQ port
Dot1Q port Yes No No Dot1Q port
QinQ port Yes Yes No  Dot1Q port
QinQ port Yes No No QinQ port

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.
 

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 

When a connection is created, the connection transitions through various states within the Equinix infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status at the enterprise's end.

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_APPROVAL NOT_AVAILABLE Connection request has been sent to seller and is awating approval.

The seller must approve or reject the connection at this point or the "status" and "providerStatus" would remain unchanged.

PROVISIONING

or

REJECTED

 NOT_AVAILABLE

Connection establishment in progress.

or

The seller has rejected the connection.
PROVISIONED AVAILABLE

Connection established.

 

 

When an end user deletes a connection using the  API  /ecx/v3/l2/connections/{connId}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_DELETE AVAILABLE Deletion request has been sent to seller and is awating approval.

The seller must approve this delete request to disconnect the connection and to stop billing.  Keep in mind that should the seller fail to approve the deletion request, the connection would still be considered active and charged accordingly.

DEPROVISIONING

 AVAILABLE

Connection disbandment in progress.

or

The seller has rejected the request.
DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 


body: 
How to establish an L2 redundant enterprise connection?

 

 


body: 
Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get Attribute Information

2a) Get Port

Retrieve your allocated ECXF port information.

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2b) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection.

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2c) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

If you intend to create a connection to a private seller service profile, ensure that you have been authorized by the respective seller profile to access and retrieve the service profile details.

In order to do this, the seller must whitelist your email ID  by adding the email address to the private profile in the ECX portal.

For more information please refer to the ECX Fabric documentation at https://ecxfabric-documentation.equinix.com/hc/en-us/articles/360013214112-Setting-your-company-s-visibility

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 


body: 
Step 3: Create Connection

Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, secondaryName, secondaryPortUUID, secondaryVlanSTag, secondaryVlanCTag, primaryZSideVlanCTag, secondaryZSideVlanCTag

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create layer 2 redundant enterprise connection using  Dot1q and QinQ ports and a sample JSON response for this API. 

 

Redundant Connection from a Dot1Q port to a service profile with a Dot1Q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_Dot1Q",

  "profileUUID": "7a73af1a-3d74-47ac-b778-6bf455d1174e",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "4f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "873",

  "secondaryName": "JohnDoe_Dot1Q_To_Dot1Q_2",

  "secondaryVlanSTag": "873",

  "secondaryPortUUID": "7g831d3b-9740-7420-bae0-30ac1885127a",

  "sellerMetroCode": "SV"

}

 

Redundant Connection from a Dot1Q port to a service profile with a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1Q_To_QinQ",

  "profileUUID": "31b7263f-7e6a-42d0-859e-80a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",

  "primaryVlanSTag": "335",

  "secondaryName": "JohnDoe_Dot1Q_To_QinQ_2",

  "secondaryVlanSTag": "335",

  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",

  "sellerRegion": "us-sv",

  "sellerMetroCode": "SV",

  "primaryZSideVlanCTag": "421",

  "secondaryZSideVlanCTag": "521"

}

 

Redundant Connection from a QinQ port to a service profile with a Dot1Q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_QinQ_To_Dot1Q",

  "profileUUID": "2a73af1a-3c74-47ac-b778-6bf455d1174e",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "6f891d3b-972d-73d0-bae3-30ac1995197a",

  "primaryVlanSTag": "771",

  "primaryVlanCTag": "117",

  "secondaryName": "JohnDoe_QinQ_To_Dot1Q2",

  "secondaryPortUUID": "7f892d5b-993f-73f0-bae0-32ad1889197a",

  "secondaryVlanSTag": "881",

  "secondaryVlanCTag": "118",

  "sellerMetroCode": "SV"

}

 

Redundant Connection from a QinQ port to a service profile with a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

{

  "primaryName": "JohnDoe_QinQ_To_QinQ",

  "profileUUID": "32b7273f-7e7a-43d0-859e-81a7fd3b9609",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "authorizationKey": "xxxxxxxx",

  "primaryPortUUID": "7f891d3b-96d3-6d30-bae0-30ac1885197a",

  "primaryVlanSTag": "499",

  "secondaryName": "JohnDoe_QinQ_To_QinQ2",

  "secondaryVlanSTag": "2456",

  "secondaryPortUUID": "7f21d3b-93d3-6d30-cae0-33ac2895297a",

  "sellerRegion": "us-sv",

  "sellerMetroCode": "SE"

}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_Dot1Q_To_Dot1Q   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 640

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes string 641   C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 84c6616c-573a-447d-a478-9fab8fff284d   Unique identifier of the provider's service profile.
speed Yes integer 50  

Speed/Bandwidth you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  johnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 123456789   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
sellerRegion No string us-sv   An optional field that needs to be passed if requested by the service profile you intend to connect to.
secondaryName Yes string JohnDoe_QinQ_To_QinQ2   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer secondary port from which the connection would get originate.
secondaryVlanSTag Yes string 442   S-Tag/Outer-Tag of the secondary connection - A numeric character ranging from 2 to 4094.
secondaryVlanCTag Yes string 542   C-Tag/Inner-Tag of the secondary connection - A numeric character ranging from 2 to 4094.
primaryZSideVlanCTag Yes string 558   C-Tag/Inner-Tag of the primary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")
secondaryZSideVlanCTag Yes string 542   C-Tag/Inner-Tag of the secondary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")
 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to a seller/service profile (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) Vlan S-tag required Vlan C-tag required ZSide Vlan C-tag required Port Type ( Z-side)
Dot1Q port Yes No Yes QinQ port
Dot1Q port Yes No No Dot1Q port
QinQ port Yes Yes No Dot1Q port
QinQ port Yes No No QinQ port

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"

    "secondaryConnectionId": "888d4c1-5444-4511-b2e4-51f06f062974"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.
 
secondaryConnectionId string 888d4c1-5444-4511-b2e4-51f06f062974 Indicates the secondary connection ID.

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 

When a connection is created, the connection transitions through various states within the Equinix infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status in Equinix and the "providerStatus" indicates the status at the enterprise's end.

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_APPROVAL NOT_AVAILABLE Connection request has been sent to seller and is awating approval.

The seller must approve or reject the connection at this point or the "status" and "providerStatus" would remain unchanged.

PROVISIONING

or

REJECTED

 NOT_AVAILABLE

Connection establishment in progress.

or

The seller has rejected the connection.
PROVISIONED AVAILABLE

Connection established.

 

 

When an end user deletes a connection using the  API  /ecx/v3/l2/connections/{connId}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_DELETE AVAILABLE Deletion request has been sent to seller and is awating approval.

The seller must approve this delete request to disconnect the connection and to stop billing.  Keep in mind that should the seller fail to approve the deletion request, the connection would still be considered active and charged accordingly.

DEPROVISIONING

 AVAILABLE

Connection disbandment in progress.

or

The seller has rejected the request.
DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 


body: 

Connect to Myself

End users can create connections to other customer instances deployed at Equinix using either a Dot1Q port or a QinQ port. 

 

Click here to watch a video on how to connect to other Equinix customers using Equinix Cloud Exchange Fabric Portal. 


body: 
How to establish an L2 non-redundant self-connection?

 

 


body: 
Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get Attribute Information

2a) Get Port

Retrieve your allocated ECXF port information.

 

Use this API to get both the A-side (source) and Zside port (destination ) information. 

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2b) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection.

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2c) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 


body: 
Step 3: Create Connection

Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers AUTH key
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, primaryZSideVlanCTag, primaryZSidePortUUID, primaryZSideVlanSTag,

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization key is the only header that is passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization key, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create layer 2 non-redundant enterprise connection using  Dot1q and QinQ ports and a sample JSON response for this API. 

 

Non-Redundant Connection from a Dot1q port to a Dot1q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_SelfPrivate_DQ_To_DQ",

  "profileUUID": "5e79b5e4-7c5b-4201-9334-fd89b37bec47",

  "speed": 50,

  "speedUnit": "MB",

  "notifications": [

    "JohnDoe@equinix.com"

  ],

  "purchaseOrderNumber": "1234567890",

  "primaryPortUUID": "4f891d3b-973e-73e0-bae0-80ac1885197a",

  "primaryVlanSTag": "883",

  "sellerMetroCode": "DC",

  "primaryZSidePortUUID": "7f891d3b-9732-7320-bae0-30ac1885197a",
  "primaryZSideVlanSTag": "662"

}

 

Non-Redundant Connection from a Dot1q port to a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_SelfPrivate_DQ_To_QQ",

  "profileUUID": "31b7263f-3baa-4ec0-bd7b-4147ee2d04f9",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f891d3b-7e6a-73e0-859e-30ac1885197a",
  "primaryVlanSTag": "991",
  "sellerMetroCode": "DC",
  "primaryZSidePortUUID": "7f891d3b-973e-7390-bae0-30ac1885197a",
  "primaryZSideVlanSTag": "601",
  "primaryZSideVlanCTag": "483"
}

 

 

Non-Redundant Connection from a QinQ port to a Dot1q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_SelfPrivate_Q_To_DQ",

  "profileUUID": "7e8e41ac-8d4e-4d6d-9w5-eb532ad5fe73",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f345d3b-973d-73d0-bae0-30ac1435697a",
  "primaryVlanSTag": "756",
  "sellerMetroCode": "DC",
  "primaryVlanCTag": "984",
  "primaryZSidePortUUID": "7f891d3b-9732-7320-bae0-30ac1456197a",
  "primaryZSideVlanSTag": "550"
}

 

Non-Redundant Connection from a QinQ port to a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_SelfPrivate_Q_To_Q",

  "profileUUID": "fa2e4cdd-3baa-4ec0-bd7b-434572d04f9",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f579d3b-973d-73d0-bae0-30ac1885197a",
  "primaryVlanSTag": "771",
  "sellerMetroCode": "DC",
  "primaryZSidePortUUID": "7f891d3b-9739-7390-bae0-30ac1976197a",
  "primaryZSideVlanSTag": "471"
}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_AWS_QinQ   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 99991d3b-9750-7500-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes string 775

 

 C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 999552b-39b0-49ea-a232-005088dc9c86   Unique identifier of the provider's service profile.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 
 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to a seller/service profile (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) Vlan S-tag required Valan C-tag required ZSide Vlan C-tag required Port Type ( Z-side)
Dot1Q port Yes No Yes QinQ port
Dot1Q port Yes No No Dot1Q port
QinQ port Yes Yes No  Dot1Q port
QinQ port Yes No No QinQ port
 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.
 

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 

When a connection is created, the connection transitions through various states within the Equinix infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status at Equinix A-side and the "providerStatus" indicates the status at Equinix Z-side.

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_AUTO_APPROVAL NOT_AVAILABLE

Connection request has been sent for auto approval.

 

As the connection is within the same organization (i.e. A side and Z side) the connection would fall under auto approval.
PROVISIONING NOT_AVAILABLE

Connection establishment in progress.
PROVISIONED AVAILABLE Connection established.
 

 

When an end user deletes a connection using the  API  /ecx/v3/l2/connections/{connId}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description

DEPROVISIONING

 AVAILABLE

Connection disbandment in progress.
DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 

 


body: 
How to establish an L2 redundant self-connection?

 

 


body: 
Step 1: Authenticate

Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.

 

Refer to Generating a Client ID and Client Secret key under Getting Started section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.

 

If you are unaware of your user credentials for Equinix Cloud Exchange Fabric, contact your local Equinix Service Desk. 

 


body: 
Step 2: Get Attribute Information

2a) Get Port

Retrieve your allocated ECXF port information.

 

Use this API to get both the A-side (source) and Zside port (destination ) information. 

 

Refer to Get Port under the API Reference section for instructions on how to retrieve available ports. You may skip this step if you already know the available port information.

 

2b) Get Metros

Gather available metro options with ECX Fabric ports.

 

Use this API to get the metro codes for metros from which you wish to create a connection.

 

Refer to Get Metros under the API Reference section for instructions on how to get the metro code. You may skip this step if you already know the metro code.  

 

2c) Get Service Profile

Identify all seller/service profiles available for a given metro or metros.

 

Refer to Get Services under the API Reference section for instructions on how to get the seller profile. You may skip this step if you already know the service profile details.

 


body: 
Step 3: Create Connection

Post Connections

POST /ecx/v3/l2/connections
Method POST
URL or End Point /ecx/v3/l2/connections
Headers AUTH key
Query Parameters Not applicable
Body Parameters primaryName, primaryPortUUID, primaryVlanSTag,  primaryVlanCTag,  profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, secondaryName, secondaryPortUUID, secondaryVlanSTag, secondaryVlanCTag, primaryZSideVlanCTag, secondaryZSideVlanCTag, primaryZSidePortUUID, primaryZSideVlanSTag, secondaryZSidePortUUID, secondaryZSideVlanSTag

 

The POST connections API creates a Layer 2 Connection between your port and the destination service profile. The authorization key is the only header that is passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization key, refer to Requesting Access and Refresh tokens section under Getting Started.

 

The following screenshots show sample curl requests to create layer 2 redundant enterprise connection using  Dot1q and QinQ ports and a sample JSON response for this API. 

 

Redundant Connection from a Dot1Q port to a Dot1Q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Self_R_Pvt_D2D",

  "profileUUID": "31b7263f-7e6a-42d0-859e-80a7fd3b9609",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f891d3b-973c-73c0-bae0-30ac1885197a",
  "primaryVlanSTag": "739",
  "secondaryName": "JohnDoe2_Self_R_Pvt_D2D",
  "secondaryVlanSTag": "559",
  "secondaryPortUUID": "7f891d3b-9744-7440-bae0-30ac1885197a",
  "sellerMetroCode": "SV",
  "primaryZSidePortUUID": "7f891d3b-99c8-9c80-bae0-30ac1885197a",
  "primaryZSideVlanSTag": "739",
  "secondaryZSideVlanSTag": "639",
  "secondaryZSidePortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a"
}

 

Redundant Connection from a Dot1Q port to a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Self_R_Pvt_D2Q",

  "profileUUID": "19bd99fa-9b5a-4d06-9db0-b0f308a43e3e",
  "speed": 500,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "874",
  "secondaryName": "JohnDoe2_Self_R_Pvt_D2Q",
  "secondaryVlanSTag": "738",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "sellerMetroCode": "DC",
  "primaryZSidePortUUID": "7f891d3b-9739-7390-bae0-30ac1885197a",
  "primaryZSideVlanSTag": "762",
  "secondaryZSideVlanSTag": "421",
  "secondaryZSidePortUUID": "7f891d3b-973a-73a0-bae0-30ac1885197a",
  "primaryZSideVlanCTag": "972",
  "secondaryZSideVlanCTag": "864"
}

 

Redundant Connection from a QinQ port to a Dot1Q port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Self_R_Pvt_Q2D",

  "profileUUID": "31b7263f-7e6a-42d0-859e-80a7fd3b9609",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",
  "primaryVlanSTag": "3994",
  "secondaryName": "JohnDoe2_Self_R_Pvt_Q2D",
  "secondaryVlanSTag": "3773",
  "secondaryPortUUID": "7f891d3b-973f-73f0-bae0-30ac1885197a",
  "primaryVlanCTag": "3449",
  "secondaryVlanCTag": "3254",
  "sellerMetroCode": "SV",
  "primaryZSidePortUUID": "7f891d3b-9747-7470-bae0-30ac1885197a",
  "primaryZSideVlanSTag": "2467",
  "secondaryZSideVlanSTag": "2553",
  "secondaryZSidePortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a"
}

 

Redundant Connection from a QinQ port to a QinQ port 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Self_R_Pvt_Q2Q",

  "profileUUID": "19bd99fa-9b5a-4d06-9db0-b0f308a43e3e",
  "speed": 500,
  "speedUnit": "MB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7f891d3b-973d-73d0-bae0-30ac1885197a",
  "primaryVlanSTag": "660",
  "secondaryName": "JohnDoe2_Self_R_Pvt_Q2Q",
  "secondaryVlanSTag": "620",
  "secondaryPortUUID": "7f891d3b-973f-73f0-bae0-30ac1885197a",
  "sellerMetroCode": "DC",
  "primaryZSidePortUUID": "7f891d3b-9739-7390-bae0-30ac1885197a",
  "primaryZSideVlanSTag": "719",
  "secondaryZSideVlanSTag": "638",
  "secondaryZSidePortUUID": "7f891d3b-9738-7380-bae0-30ac1885197a"
}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryName Yes string JohnDoe_Dot1Q_To_Dot1Q   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer primary port from which the connection would get originate.
primaryVlanSTag Yes integer 640

 

S-Tag/Outer-Tag of the primary connection - A numeric character ranging from 2 - 4094.
primaryVlanCTag Yes string 641   C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
profileUUID Yes string 84c6616c-573a-447d-a478-9fab8fff284d   Unique identifier of the provider's service profile.
speed Yes integer 50  

Speed/Bandwidth you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  johnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 123456789   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
sellerRegion No string us-sv   An optional field that needs to be passed if requested by the service profile you intend to connect to.
secondaryName Yes string JohnDoe_QinQ_To_QinQ2   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer secondary port from which the connection would get originate.
secondaryVlanSTag Yes string 442   S-Tag/Outer-Tag of the secondary connection - A numeric character ranging from 2 to 4094.
secondaryVlanCTag Yes string 542   C-Tag/Inner-Tag of the secondary connection - A numeric character ranging from 2 to 4094.
primaryZSideVlanCTag Yes string 558   C-Tag/Inner-Tag of the primary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")
secondaryZSideVlanCTag Yes string 542   C-Tag/Inner-Tag of the secondary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")
 

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to a seller/service profile (Z-side). Ensure to add the correct S tag or C tag based on your port type.

 

Port Type (A-side) Vlan S-tag required Vlan C-tag required ZSide Vlan C-tag required Port Type ( Z-side)
Dot1Q port Yes No Yes QinQ port
Dot1Q port Yes No No Dot1Q port
QinQ port Yes Yes No Dot1Q port
QinQ port Yes No No QinQ port
 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Connection Saved Successfully",
    "primaryConnectionId": "9999a8-0e07-44d0-944c-88a25d8d28f7"

    "secondaryConnectionId": "888d4c1-5444-4511-b2e4-51f06f062974"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection Saved Successfully Indicates the status of the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID.
 
secondaryConnectionId string 888d4c1-5444-4511-b2e4-51f06f062974 Indicates the secondary connection ID.
 

 

Once the POST Connections API is successfully called, you may check the status of the connection using the API /ecx/v3/l2/connections/{connId}

 

When a connection is created, the connection transitions through various states within the Equinix infrastructure. These states can be monitored using the response attributes of the API /ecx/v3/l2/connections/{connId}. The "status" attribute indicates the connection status at Equinix A-side and the "providerStatus" indicates the status at Equinix Z-side.

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description
PENDING_AUTO_APPROVAL NOT_AVAILABLE

Connection request has been sent for auto approval.

 

As the connection is within the same organization (i.e. A side and Z side) the connection would fall under auto approval.
PROVISIONING NOT_AVAILABLE

Connection establishment in progress.
PROVISIONED AVAILABLE Connection established.
 

 

When an end user deletes a connection using the  API  /ecx/v3/l2/connections/{connId}  the connection transitions through the following states within the Equinix infrastructure. 

 

Equinix States under /ecx/v3/l2/connections/{connId}
"status" attribute values "providerStatus" attribute values Description

DEPROVISIONING

 AVAILABLE

Connection disbandment in progress.
DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 

 



body: 

GET User Port

GET /port/userport
 Method  GET
 URL or End Point  /ecx/v3/port/userport
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The userport API retrieves details of all assigned and available ports for the user credentials submitted. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed. 

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to obtain designated ports and a JSON response containing details of port information. 

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

[
    {
        "uuid": "9a1b30c7-baaf-aaf0-96e0-30ac188c7099",
        "name": "johnDoePort",
        "provisionStatus": "ADDED",
        "region": "AMER",
        "device": "1C00A955256C0027A0D544A68EE8C911",
        "totalBandwidth": 1000000000,
        "buyout": true,
        "custOrgId": "99966",
        "ibx": "SV1",
        "metroCode": "SV",
        "metroDescription": "Silicon Valley",
        "deviceGroup": "2",
        "devicePriority": "Primary",
        "encapsulation": "Dot1q",
        "viewPortPermission": true,
        "placeVcOrderPermission": true,
        "createdDate": "2018-11-07 21:56:59.0",
        "lastUpdatedDate": "2018-11-07 21:56:59.0",
        "userPorts": [
            {
                "bandwidth": 1000000000,
                "crossConnectId": "20883104"
            }
        ],
        "layer3Enabled": true,
        "lag": false
    }
]

 

It is important to take note of the metroCode attribute received in the response as this indicates where the connection would be established from and can be passed as a query string in the API /ecx/v3/l2/metros to retrieve all available metros where the user can connect to.

 

The description of the response payload is as follows:

 

Field Name Type Example Description
uuid string 9a1b30c7-baaf-aaf0-96e0-30ac188c7099 The unique identifier of the port.
name string johnDoePort The name assigned to the port.
provisionStatus string

ADDED

PROVISIONED

Indicates whether a port has been assigned or is ready for connection.
region string

AMER

EMEA

APAC

 Indicates the region in which the port resides.
device string 1C00A955256C0027A0D544A68EE8C911 The device number/name on which the port resides.
totalBandwidth integer 1000000000 Port Bandwidth in bytes.
buyout boolean

true

false

 If buyout=true, then it is an unlimited connections port that allows multiple connections on the port at no additional charge. If buyout=false then it is a standard port.
custOrgId string 99966 The id of the customer who owns the port.
ibx string SV1 The Equinix IBX where the port resides.
metroCode string

SV

 The metro code where the port resides.
metroDescription string Silicon Valley The metro name where the port resides.
deviceGroup string 2 The Group id/number of the device where the port resides.
devicePriority string

Primary

"Secondary

 The priority of the device (Primary/secondary).
encapsulation string

Dot1q

QinQ

 The VLAN encapsulation of the port (Dot1q or QinQ).
viewPortPermission boolean

true

false

 If the value is True, Then can only view out going connections from the port, if not, otherwise.
placeVcOrderPermission boolean

true

false

 If the value is True, Then you can create modify or delete the connection.
createdDate string 2018-11-07 21:56:59.0" The date on which the port was created.
lastUpdatedDate string 2018-11-07 21:56:59.0 The date on which the port was last updated.
userPorts array   An array containing multiple port information.
bandwidth integer 1000000000 Member port bandwidth in bytes.
crossConnectId string 20883104 Cross-connect connection IDs belonging to the member ports.
lasyer3Enabled boolean

true

false

 Indicates whether or not the port is enabled for Layer 3 connections.
lag boolean

true

false

 Indicates whether or not the port is part of a Link Aggregation Group (LAG).

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

L2 APIs


body: 

GET Metros

GET /common/metros
 Method  GET
 URL or End Point  /ecx/v3/l2/common/metros
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The metros API returns all available metros with ECX fabric ports where the user can connect to. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request and JSON response for this API. The response indicates that a user can connect to Amsterdam (AM) from LD, FR, PA, DB, SK, ZH, HE, ML, WA and MD and vice versa.

 

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": [
            "LD",
            "FR",
            "PA",
            "DB",
            "SK",
            "ZH",
            "HE",
            "ML",
            "WA",
            "MD"
        ]
    }
]

 

 

The description of the response payload is as follows:

 

Field name Type Example Description
name string Amsterdam The name of the metro. 
code string AM The two-character code used to denote the metro.
region string

AMER

EMEA

APAC

 The geographic region code where the metro resides. Three possible regions are “AMER”, “EMEA or “APAC”.
cloudReach string LD Other metros to which connections can be created from this location. (i.e., from Amsterdam you can create remote connections to London, Frankfurt, Paris, etc.)

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET L2 Service Profiles Services

GET l2/serviceprofiles/services
 Method  GET
 URL or End Point  /ecx/v3/l2/serviceprofiles/services
 Headers  Authorization, Content-Type
 Query Parameters  metroCode, pageNumber, pageSize
 Body  Not applicable

 

The services API returns all L2 seller profiles (services) such as AWS - Direct Connect, Azure - Express Route etc for a given metro. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to obtain details of L2 sellers within DC, USA and a JSON response containing details of a sample seller named John-Doe Demo. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles/services?pageSize=20&pageNumber=0&metroCode=Dc"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
pageSize No Integer 20   The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
pageNumber No Integer 1   The page number of the page which is currently being displayed. 
metroCode No array[string]

DC

 

 The 2 character metro code of the metro for which to retrieve service profiles. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv). 

 

{
    "isLastPage": false,
    "totalCount": 23,
    "isFirstPage": true,
    "pageSize": 20,
    "content": [
        {
            "uuid": "97d1850f-4df0-468c-9281-fa7b0dfa2096",
            "name": "John-Doe Demo",
            "connectionNameLabel": "JohnDoeConnection",
            "requiredRedundancy": false,
            "allowCustomSpeed": false,
            "speedBands": [
                {
                    "speed": 50,
                    "unit": "MB"
                },
                {
                    "speed": 200,
                    "unit": "MB"
                },
                {
                    "speed": 500,
                    "unit": "MB"
                },
                {
                    "speed": 1000,
                    "unit": "MB"
                }
            ],
            "metros": [
                {
                    "code": "SV",
                    "name": "Silicon Valley",
                    "ibxs": [
                        "SV5"
                    ],
                    "displayName": "Silicon Valley"
                },
                {
                    "code": "DC",
                    "name": "Ashburn",
                    "ibxs": [
                        "DC11"
                    ],
                    "displayName": "Ashburn"
                }
            ],
            "createdDate": "2018-12-07T13:31:58.525Z",
            "createdBy": "John-Doe",
            "lastUpdatedDate": "2018-12-07T13:58:28.258Z",
            "lastUpdatedBy": "John-Doe",
            "vlanSameAsPrimary": false,
            "tagType": "BOTH",
            "apiAvailable": false,
            "selfProfile": false,
            "speedFromAPI": false,
            "profileEncapsulation": "Qinq",
            "authorizationKey": "[a-z|A-z|0-9]",
            "organizationName": "John-Doe-Corp",
            "private": false,
            "features": {
                "cloudReach": true,
                "testProfile": false
            }
        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
isLastPage boolean

true

false

 Indicates whether the page being displayed is the last page.
totalCount integer 23 The number of items returned as response for the API request.
isFirstPage boolean

true

false

 Indicates whether the page being displayed is the first page.
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content array   An array containing the response data.
uuid string 97d1850f-4df0-468c-9281-fa7b0dfa2096 The unique identifier of the service profile.
name string John-Doe Demo The name assigned to the service profile.
connectionNameLabel string JohnDoeConnection This is the label the user will see when creating a connection name for their connection.
requiredRedundancy boolean

true

false

Indicates whether or not redundant connections are required when connecting to this service profile.

If requireRedundancy” = true, you would need two ports, a primary port with a primary connection and a secondary port with a secondary connection, or one port and two connections (one primary and one secondary).
allowCustomSpeed boolean

true

false

 Indicates whether or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
speedBands array   An array containing the speeds/bandwidth ranges allowed when creating connections to this profile.
speed double

50

200

500

1000

 Bandwidth speed.
unit string MB Bandwidth speed unit.
metros array   The metros associated with this profile where connections can be created.
code string SV The metro code denoting metros where connections to this service profile can be created.
name string Silicon Valley The actual metro name where connections to this service profile can be created.
ibxs string SV5 Equinix IBXs associated with this metro.
displayName string Silicon Valley The name displayed when referring to this metro.
createdDate string 2018-12-07T13:31:58.525Z The date the service profile was created.
createdBy string John-Doe The username who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The last date the service profile was updated.
lastUpdatedBy string John-Doe The user who last updated the service profile.
vlanSameAsPrimary boolean

true

false

 Indicates whether or not to use the same VLAN for the primary connection as for the secondary connection.
tagType string

CTAGED

BOTH

NAMED

 The type of tagging to be used for connections to this service profile. The default value is CTAGED.
apiAvailable boolean

true

false

 Indicates whether or not API integration has been performed for connections to this profile.
selfProfile boolean

true

false

 Indicates whether the profile belongs to your organization.
speedfromAPI string

true

false

 Bandwidth of the cloud service provider for this connection according to the service provider.
profileEncapsulation string

Dot1q

Qinq

 The port encapsulation type for this profile, can be either Dot1q or Qinq.
authorizationKey string [a-z|A-z|0-9] A sample authorization key expression to be used by the user/customer when creating connections to this profile. e.g. - Account ID for AWS, Service key for Azure, etc
organizationName string John-Doe-Corp Organization name associated with this service profile.
private boolean

true

false

 Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.)
features object   Contains feature related information such as cloudReach, testProfile, etc.  
cloudReach boolean

true

false

 Indicates whether or not connections to this profile can be created from remote metros.
testProfile boolean

true

false

 Indicates whether or not this profile can be used for test connections.
pageNumber integer 0 The page number of the page which is currently being displayed. 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET L2 Service Profiles Services {uuid}

GET l2/serviceprofiles/services/{uuid}
 Method  GET
 URL or End Point  /ecx/v3/l2/serviceprofiles/services/{uuid}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The services API returns the L2 service profile for a given profile uuid. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

Uuid is an identifier unique for each service profile.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to obtain L2 seller details for the ID 97d1850f-4df0-468c-9281-fa7b0dfa2096 and a JSON response containing details of a sample seller named John-Doe Demo. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles/services/97d1850f-4df0-468c-9281-fa7b0dfa2096"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the URL parameter is as follows:

 

URL Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string 97d1850f-4df0-468c-9281-fa7b0dfa2096

 

 Identifier of service profile.
 

 

{
    "uuid": "97d1850f-4df0-468c-9281-fa7b0dfa2096",
    "name": "John-Doe Demo",
    "connectionNameLabel": "JohnDoeConnection",
    "requiredRedundancy": false,
    "allowCustomSpeed": false,
    "speedBands": [
        {
            "speed": 50,
            "unit": "MB"
        },
        {
            "speed": 200,
            "unit": "MB"
        },
        {
            "speed": 500,
            "unit": "MB"
        },
        {
            "speed": 1000,
            "unit": "MB"
        }
    ],
    "metros": [
        {
            "code": "SV",
            "name": "Silicon Valley",
            "ibxs": [
                "SV5"
            ],
            "displayName": "Silicon Valley"
        },
        {
            "code": "DC",
            "name": "Ashburn",
            "ibxs": [
                "DC11"
            ],
            "displayName": "Ashburn"
        }
    ],
    "createdDate": "2018-12-07T13:31:58.525Z",
    "createdBy": "John-Doe",
    "lastUpdatedDate": "2018-12-07T13:58:28.258Z",
    "lastUpdatedBy": "John-Doe",
    "vlanSameAsPrimary": false,
    "tagType": "BOTH",
    "apiAvailable": false,
    "selfProfile": false,
    "speedFromAPI": false,
    "profileEncapsulation": "Qinq",
    "authorizationKey": "[a-z|A-z|0-9]",
    "organizationName": "John-Doe-Corp",
    "private": false,
    "features": {
        "cloudReach": true,
        "testProfile": false
    }
}

 

The description of the response payload is as follows:

 

Field Name  Type Example Description
uuid string 97d1850f-4df0-468c-9281-fa7b0dfa2096 The unique identifier of the service profile.
name string John-Doe Demo The name assigned to the service profile.
connectionNameLabel string JohnDoeConnection This is the label the user will see when creating a connection name for their connection.
requiredRedundancy boolean

true

false

 Indicates whether or not redundant connections are required when connecting to this service profile.
allowCustomSpeed boolean

true

false

 Indicates whether or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
speedBands string   The speeds/bandwidth ranges allowed when creating connections to this profile.
speed double

50

200

500

1000

 Bandwidth speed.
unit string MB Bandwidth speed unit.
metros array   The metros associated with this profile where connections can be created.
code string SV The metro code denoting metros where connections to this service profile can be created.
name string Silicon Valley The actual metro name where connections to this service profile can be created.
ibxs string SV5 Equinix IBXs associated with this metro.
displayName string Silicon Valley The name displayed when referring to this metro.
createdDate string 2018-12-07T13:31:58.525Z The date the service profile was created.
createdBy string John-Doe The username who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The last date the service profile was updated.
lastUpdatedBy string John-Doe The user who last updated the service profile.
vlamSameAsPrimary boolean

true

false

 Indicates whether or not to use the same VLAN for the primary connection as for the secondary connection.
tagType string

CTAGED

BOTH

NAMED

 The type of tagging to be used for connections to this service profile.  The default value is CTAGED.
apiAvailable boolean

true

false

 Indicates whether or not API integration has been performed for connections to this profile.
selfProfile boolean

true

false

 Indicates whether the profile belongs to your organization.
speedfromAPI string

true

false

 The bandwidth of the cloud service provider for this connection according to the API.
profileEncapsulation string

Dot1q  

Qinq

 The type of port encapsulation. Applicable values are Dot1q or QinQ.
authorizationKey string [a-z|A-z|0-9] A sample authorization key expression to be used by the user/customer when creating connections to this profile. e.g. - Account ID for AWS, Service key for Azure, etc
organizationName string John-Doe-Corp Oraganization name associated with the service profile.
private boolean

true

false

 Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.
features object   Contains feature related information such as cloudReach, testProfile.
cloudReach boolean

true

false

 Indicates whether or not connections to this profile can be created from remote metros.
testProfile boolean

true

false

 Indicates whether or not this profile can be used for test connections.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

 GET L2 Validate Authorization Key

GET l2/connections/validateAuthorizationKey
 Method  GET
 URL or End Point  /ecx/v3/l2/connections/validateAuthorizationKey
 Headers  Authorization, Content-Type
 Query Parameters  authorizationKey,metroCode, profileId, region 
 Body  Not applicable

 

The validateAuthorizationKey API validates an L2 service key against an L2 destination service profile. In other words,  this API checks if the user is authorized by the service provider to create a connection to this metro (destination). The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to validate an L2 service key against a service profile in DC, and its respective JSON response. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/connections/validateAuthorizationKey?authorizationKey=991040a8-2e08-48b9-b0f8-8c5f87dfbx6a&metroCode=DC&profileId=x1384t22-bbe0-4e43-ax37-95beeg9d254d&region=AMER

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
authorizationKey Yes string 991040a8-2e08-48b9-b0f8-8c5f87cfbx6a   Connection credentials such as AWS account ID for AWS, service key for Azure etc.
metroCode Yes string DC

 

The two-character code used to denote the metro.
profileId Yes string x1384t22-bbe0-4e43-ax37-95beeg9d254d   The unique identifier of the service profile.
region Yes string AMER

"AMER"

"EMEA"

"APAC"

 Indicates the region in which the port resides.

 

{
    "message": "Authorization key provided is valid",
    "status": "VALID",
    "primary": {
        "bandwidth": "50MB"
    },
    "secondary": {
        "bandwidth": "50MB"
    }
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Authorization key provided is valid A message indicating whether the submitted key is valid or invalid.
status string

VALID

INVALID

 Indicates whether the submitted key is valid or invalid.
primary object  

An object containing primary connection information.
bandwidth string 50MB The bandwidth of the primary connection.
secondary object   An object containing secondary connection information.
bandwidth string 50MB The bandwidth of the secondary connection.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET L2 Buyer Connections

GET l2/buyer/connections
 Method  GET
 URL or End Point  /ecx/v3/l2/buyer/connections
 Headers  Authorization, Content-Type
 Query Parameters  status, metroCode, buyerPortName, buyerPortUUID, searchtType, subAccount, pageNumber, pageSize
 Body  Not applicable

 

This API returns all outgoing connections of the user. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to obtain all outgoing L2 connections for user credentials submitted and its JSON response. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/buyer/connections?metroCode=DC"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

Query Parameter Name Mandatory Type Example Applicable Values Description
status No array[string] PROVISIONED

"PROVISIONED"

"DEPROVISIONED"

"PENDING_APPROVAL"

 Indicates the status of the connection at Equinix's end (A Side).
metroCode No string DC

 

 The 2 character metro code of the metro for which to retrieve service profiles. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv). 
buyerPortName No string JohnDoePort   The name of the buyer port.
buyerPortUUID No string 006d08e2-788e-4c83-82d3-07b1787644a5   The unique identifier of the buyer port.
sellerPortName No string JohnDoe2Port   The name of the seller port.
searchType No string AND

"AND"

"OR"

 Querying operations.
subAccount No string 456   Can only be used by resellers.
pageNumber No integer 1   The page number of the page which is currently being displayed. 
pageSize No integer 20   The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 

 

{
    "isFirstPage": true,
    "totalCount": 467,
    "isLastPage": false,
    "pageSize": 20,
    "content": [
        {
            "buyerOrganizationName": "JOHN-DOE-ORG",
            "uuid": "006d08e2-788e-4c83-82d3-07b1787644a5",
            "name": "SAL-AZURE-TR-SEC-20",
            "vlanSTag": 200,
            "portUUID": "66284add-86d1-6d10-b4e0-30ac094f8af1",
            "portName": "JOHN DOE TEST",
            "asideEncapsulation": "dot1q",
            "metroCode": "TR",
            "metroDescription": "Toronto",
            "providerStatus": "DEPROVISIONED",
            "status": "DEPROVISIONED",
            "billingTier": "Up to 50 MB",
            "authorizationKey": "99973578-36f9-47f8-b12f-afa3faf02d06",
            "speed": 50,
            "speedUnit": "MB",
            "redundancyType": "secondary",
            "redundancyGroup": "28c02121-f093-4340-90c9-081b17b239c8",
            "sellerMetroCode": "TR",
            "sellerMetroDescription": "Toronto",
            "sellerServiceName": "Azure Express Route",

            "sellerServiceUUID": "a1390b22-bbe0-4e93-ad37-85beef9d254d",
            "sellerOrganizationName": "John Doe Org",
            "notifications": [
                "JohnDoe@equinix.com"
            ],

            "namedTag": "Private",
            "createdDate": "2018-08-30T04:20:36.033Z",
            "createdBy": "JohnDoe@equinix.com",
            "createdByFullName": "JohnDoe",
            "createdByEmail": "JohnDoe@equinix.com",
            "lastUpdatedDate": "2018-09-14T02:21:06.425Z",
            "deletedBy": "JohnDoe@equinix.com",
            "deletedDate": "2018-09-02T16:03:36.349Z",
            "deletedByEmail": "JohnDoe@equinix.com",
            "zSidePortName": "John-Port",
            "zSidePortUUID": "6f5680ea-1513-5130-50e0-30ac094f83ec",
            "zSideVlanSTag": 8,
            "remote": false,
            "private": false,
            "self": false

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content object   An array containing the response data.
asideEncapsulation string

"Dot1q"

"Qinq"

 The encapsulation of the buyer port (Dot1q or QinQ).
authorizationKey string 99973578-36f9-47f8-b12f-afa3faf02d06 The authorization key to be used by the user/customer when creating connections to this profile.
billingTier string Up to 50 MB Billing tier for connection.
buyerOrganizationName string JOHN-DOE-ORG Buyer organization name.
createdBy string JohnDoe@equinix.com The username who created the connection.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the connection.
createdByFullName string JohnDoe The full name of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
lastUpdatedBy string   The username who updated the connection.
lastUpdatedDate string   The date on which the connection was last updated.
lastUpdatedByEmail string   The email ID of the user who updated the connection.
lastUpdatedByFullName string   The full name of the user who updated the connection.
namedTag string Private The type of peering you would like to set up with Azure Express Route.
notification array   Email address of the contact to be notified for any updates on the connection.
metroCode string TR The metro code denoting the source metro from where the connection has been created. 
metroDescription string   The metro name where connections to this service profile can be created. 
name string   Name of the connection.
namedTag string

Private

Public

Microsoft 

Manual

 The type of peering for Azure Express Route.
portName string JOHN DOE TEST The name assigned to the port.
portUUID string 66284add-86d1-6d10-b4e0-30ac094f8af1 The unique identifier of the port.
private boolean

true

false

 Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.)
purchaseOrderNumber string   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
redundancyGroup string 28c02121-f093-4340-90c9-081b17b239c8 Grouping of a primary and secondary connection using a unique ID.
redundancyType string secondary The type of connection.
remote boolean

true

false

 Indicates whether the connection is a remote connection.  (i.e. if the seller and buyer metros are different then it's a remote connection)
self boolean

true

false

 Indicates whether the connection belongs to your organization. (i.e. source and destination belongs to your organization)
sellerMetroCode string TR The metro code denoting the destination metro where the connection has been created to. 
sellerMetroDescription string Toronto The metro name indicating the destination metro where the connection has been created to. 
sellerOrganizationName string John Doe Org Seller organization name associated with the connection.
sellerServiceName string Azure Express Route Seller service associated with the connection.
sellerServiceUUID string a1390b22-bbe0-4e93-ad37-85beef9d254d Seller service ID associated with the connection.
speed integer 50 Bandwidth speed
speedUnit string MB The unit of bandwidth speed.
providerStatus string

"DEPROVISIONED"

"PROVISIONED"

"PENDING_APPROVAL"

"NOT_AVAILABLE"

"DEPROVISIONING"

"PROVISIONING"

"FAILED"

"PENDING_BGP"

"AVAILABLE"

"OUTOFBANDWIDTH"

"ERROR"

 The status of the connection at the service provider's end.
status string

DEPROVISIONED

PROVISIONED

 The status of the connection at Equinix's end.
uuid string 006d08e2-788e-4c83-82d3-07b1787644a5 The unique identifier of the connection.
vlanSTag string 4 Stag name of the connection.
zSidePortName string John-Port

The name of the Z side port.
zSidePortUUID string 6f5680ea-1513-5130-50e0-30ac094f83ec

The unique identifier of the Z side port.
zSideVlanCTag integer 5 The C Tag of the Z side port.
zSideVlanSTag integer 8 The S Tag of the Z side port.
isFirstPage boolean

true

false

 Indicates whether the page being displayed is the first page.
isLastPage boolean

true

false

 Indicates whether the page being displayed is the last page.
pageNumber integer 20 The page number of the page which is currently being displayed. 
totalCount integer 467 The number of items returned as the response for the API request.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

GET L2 Connections {uuid}

GET l2/connections/{uuid}
 Method  GET
 URL or End Point  /ecx/v3/l2/connections/{uuid}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The connections API returns connection details for a given L2 connection connID. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

Uuid is an identifier unique for each connection.

 

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request to obtain L2 connection details for the ID 97d1850f-4df0-468c-9281-fa7b0dfa2096 and a JSON response containing connection information. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/connections/006d08e2-788e-4c83-82d3-07b1787644a5"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the URL parameter is as follows:

 

URL Parameter Name Mandatory Type Example Applicable Values Description
uuid Yes string 006d08e2-788e-4c83-82d3-07b1787644a5

 

 Identifier of connection.
 

 

{
    "isFirstPage": true,
    "totalCount": 467,
    "isLastPage": false,
    "pageSize": 20,
    "content": [
        {
            "buyerOrganizationName": "JOHN-DOE-ORG",
            "uuid": "006d08e2-788e-4c83-82d3-07b1787644a5",
            "name": "John-Doe",
            "vlanSTag": 200,
            "portUUID": "66284add-86d1-6d10-b4e0-30ac094f8af1",
            "portName": "JOHN-DOE-PORT",
            "asideEncapsulation": "dot1q",
            "metroCode": "TR",
            "metroDescription": "Toronto",
            "providerStatus": "DEPROVISIONED",
            "status": "DEPROVISIONED",
            "billingTier": "Up to 50 MB",
            "authorizationKey": "12238-36f9-47f8-c12g-afr33af02d06",
            "speed": 50,
            "speedUnit": "MB",
            "redundancyType": "secondary",
            "redundancyGroup": "28c02121-f093-4340-90c9-081b17b239c8",
            "sellerMetroCode": "TR",
            "sellerMetroDescription": "Toronto",
            "sellerServiceName": "Azure Express Route",

            "sellerServiceUUID": "a1390b22-bbe0-4e93-ad37-85beef9d254d",
            "sellerOrganizationName": "JOHN ORG",
            "notifications": [
                "JohnDoe@equinix.com"
            ],

            "namedTag": "Private",
            "createdDate": "2018-08-30T04:20:36.033Z",
            "createdBy": "JohnDoe@equinix.com",
            "createdByFullName": "John Doe",
            "createdByEmail": "JohnDoe@equinix.com",
            "lastUpdatedDate": "2018-09-14T02:21:06.425Z",
            "deletedBy": "JohnDoe@equinix.com",
            "deletedDate": "2018-09-02T16:03:36.349Z",
            "deletedByEmail": "JohnDoe@equinix.com",
            "zSidePortName": "JOHN-DOE-PORT-B",
            "zSidePortUUID": "6f5680ea-1513-5130-50e0-30ac094f83ec",
            "zSideVlanSTag": 8,
            "remote": false,
            "private": false,
            "self": false

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field Type Example Description
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content object   An array containing the response data.
asideEncapsulation string

Dot1q

Qinq

 The encapsulation of the buyer port (Dot1Q or QinQ).
authorizationKey string 1233548-36g9-47f8-b12f-afa3faf02d06 The authorization key to be used by the user/customer when creating connections to this profile.
billingTier string Up to 50 MB Billing tier for connection.
buyerOrganizationName string JOHN-DOE-ORG Buyer organization name.
createdBy string JohnDoe@equinix.com The username who created the connection.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the connection.
createdByFullName string John Doe The full name of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
lastUpdatedBy string   The username who updated the connection.
lastUpdatedDate string 2018-09-14T02:21:06.425Z The date on which the connection was last updated.
lastUpdatedByEmail string   The email ID of the user who updated the connection.
lastUpdatedByFullName string   The full name of the user who updated the connection.
namedTag string Private The type of peering you would like to set up with Azure Express Route.
notification array JohnDoe@equinix.com Email address of the contact to be notified for any updates on the connection.
metroCode string TR The metro code denoting the source metro from where the connection has been created. 
metroDescription string Toronto The metro name where connections to this service profile can be created. 
name string John-Doe Name of the connection.
namedTag string

"Private" 

"Public" 

"Microsoft" 

"Manual"

 The type of peering for Azure Express Route.
portName string JOHN-DOE-PORT The name assigned to the port.
portUUID string 66284add-86d1-6d10-b4e0-30ac094f8af1 The unique identifier of the port.
private boolean

true

false

 Indicates whether or not this is a private profile. If private, it can only be available for creating connections if correct permissions are granted (i.e. not public like AWS/Azure/Oracle/Google, etc.)
purchaseOrderNumber string   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
redundancyGroup string 28c02121-f093-4340-90c9-081b17b239c8 Grouping of a primary and secondary connection using a unique ID.
redundancyType string

"primary"

"secondary"

 The type of connection.
remote boolean  

true

false

 Indicates whether the connection is a remote connection.  (i.e. if the seller and buyer metros are different then it's a remote connection)
self boolean

true

false

 Indicates whether the connection belongs to your organization. (i.e. source and destination belongs to your organization)
sellerMetroCode string TR The metro code denoting the destination metro where the connection has been created to. 
sellerMetroDescription string Toronto The metro name indicating the destination metro where the connection has been created to. 
sellerOrganizationName string JOHN ORG Seller organization name associated with the connection.
sellerServiceName string Azure Express Route Seller service associated with the connection.
sellerServiceUUID string a1390b22-bbe0-4e93-ad37-85beef9d254d Seller service ID associated with the connection.
speed integer 50 Bandwidth speed
speedUnit string

MB

GB

 The unit of bandwidth speed.
providerStatus string

DEPROVISIONED

PROVISIONED

PENDING_APPROVAL

NOT_AVAILABLE

DEPROVISIONING

PROVISIONING

FAILED

PENDING_BGP

AVAILABLE

OUTOFBANDWIDTH

ERROR

 The status of the connection at the service provider's end.
status string DEPROVISIONED The status of the connection at Equinix's end.
uuid string 006d08e2-788e-4c83-82d3-07b1787644a5 The unique identifier of the connection.
vlanSTag string 5 Stag name of the connection.
zSidePortName string JOHN-DOE-PORT-B"

The name of the Z side port.
zSidePortUUID string 66284add-86d1-6d10-b4e0-30ac094f8af1

The unique identifier of the Z side port.
zSideVlanCTag integer 5 The C Tag of the Z side port.
zSideVlanSTag integer 8 The S Tag of the Z side port.
isFirstPage boolean

true

false

 Indicates whether the page being displayed is the first page.
isLastPage boolean

true

false

 Indicates whether the page being displayed is the last page.
pageNumber integer 20 The page number of the page which is currently being displayed. 
totalCount integer 450 The number of items returned as the response for the API request.

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 


body: 

DELETE Connections {uuid}

DELETE /connections/{uuid}
 Method  DELETE
 URL or End Point

 /ecx/v3/l2/connections/{uuid}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

This API deletes the connection of a given L2 connection UUID. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

 

Uuid is an identifier unique for each connection.

 

If you are unaware of how to obtain an authorization key, refer to Requesting Access and Refresh tokens under the Getting Started section.

 

The following screenshots show a sample curl request and JSON response to delete a connection with UUID 702d31c4-c66d-49b0-a26c-a9a234e56fsb 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/connections/702d31c4-c66d-49b0-a26c-a9a234e56fsb"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "message": "Connection deleted Successfully",
    "primaryConnectionId": "702d31c4-c66d-49b0-a26c-a9a234e56fsb"
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Connection deleted Successfully Indicates the status of the Delete API call.
primaryConnectionID string 702d31c4-c66d-49b0-a26c-a9a234e56fsb Indicates the primary connection ID.
 

 

 

If you get “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

Once the API is successfully called, you may verify the status of the connection using the API /ecx/v3/l2/connections/{connId}

 


body: 

Sample Code

 


body: 

Establish a connection to AWS

Refer AWS connection sample

 


body: 

L2 APIs

Refer ECX Fabric sample to download the sample code for the following APIS:

 

1. Ports

2. Metros

3. Service Profiles

3. Validate Authorization Key 

5. BuyerConnections

 

Follow the instructions provided in the README.md for instructions on how to set up and configure the project. If you have trouble downloading the code, post the issue on our forum or contact api-support@equinix.com.

 


body: 

Status codes, Error codes & Troubleshooting tips

This section provides an overview of the common error codes as well as general guidance on how to troubleshoot and handle errors.

 


body: 

HTTP Status codes

 


body: 

200: Success

The 200 (Success) status code indicates that the HTTP request was successful. In a GET request, the response will contain an entity corresponding to the requested resource whereas, in a POST request, the response will contain an entity describing or containing the result of the action.

 

Code 200
Description Success.

 

curl -X

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

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 

This is an example of a success message.

 

[
    {
        "name": "Amsterdam",
        "code": "AM",
        "region": "EMEA",
        "cloudReach": [
            "LD",
            "FR",
            "PA",
            "DB",
            "SK",
            "ZH",
            "HE",
            "ML",
            "WA",
            "MD"
        ]
    }
]

 


body: 

400: Bad Request

The 400 (Bad request) status code indicates that server cannot process the request due to something that is perceived to be a client error (e.g. malformed request syntax, invalid request message framing, or deceptive request routing).

 

Code 400
Description Validation Error.
Generic Cause Malformed request due to field or business validation.
Quick Fix Ensure the payload sent adheres to the parameter requirements.

 

There are different types of Validation errors and this section provides sample scenarios with validation errors as well as tips on how to identify them.

 


body: 

IC-LAYER2-402


body: 
IC-LAYER2-402: Maximum 24 Characters
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause Value exceeds the configured limit of characters.
Quick Fix Rename the value to satisfy the criteria.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "Size: Max 24 characters are allowed for Primary Connection Name"
PROPERTY:   "PrimaryName"

 

Verify the length of the primaryName body parameter and modify the value accordingly.

 

curl -X

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

Rename the primaryName to John_Demo_Connection.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection_Testing_Maximum_Characters_Allowed",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 
IC-LAYER2-402: Invalid Pattern
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause Invalid argument passed to the method. 
Quick Fix Verify the PrimaryName value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "Pattern: Only number,characters,'_' and space between words are allowed"
PROPERTY:   "PrimaryName"

 

Verify PrimaryName, remove invalid characters and modify the value as shown below.

 

The endpoint URL is incorrect. Replace the ID with 

curl -X

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

Remove the '@' symbol and rename the primaryName to John_Demo_Connection.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection@",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 
IC-LAYER2-402: Invalid UUID
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause Invalid profile UUID passed to the method.
Quick Fix Verify the profile UUID value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "ValidUUID: Invalid UUID"
PROPERTY:   "profileUUID"

 

Verify profileUUID and modify the value as shown below.

 

curl -X

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

Rename the profile UUID.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91cxxxxx",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 

 


body: 
IC-LAYER2-402: Maximum 30 Characters
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause The value passed to the method exceeds the configured limit of characters.
Quick Fix Verify and rename the purchaseOrderNumber to satisfy the criteria.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "Size: Maximum 30 characters allowed on Purchase Order Number"
PROPERTY:   "purchaseOrderNumber"

 

Verify the length of the purchaseOrderNumber argument and modify the value as shown below.

 

The endpoint URL is inco 

curl -X

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

Rename the purchaseOrderNumber to "123456789".

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "12345678909999999999999999999999999999999999999999999999999999999999999999",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 
IC-LAYER2-402: Invalid Enum Value
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause Invalid value passed in enum.
Quick Fix Verify the enum value passed for speedUnit.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "ValidEnum: Invalid value. Valid values are: [MB, GB]"
PROPERTY:   "speedUnit"

 

Verify speedUnit and modify the value as shown below.

 

curl -X

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

Rename speedUnit from "XD" to "MB" or "GB".

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "XD",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 
IC-LAYER2-402: C-Tag Range
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause The value passed for Primary C-Tag exceeds the configured limit of characters.
Quick Fix Verify the Primary C-Tag value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "Range: Primary CTag must be between 2 and 4094"
PROPERTY:   "primaryVlanCTag"

 

Verify the length of the primaryVlanCTag and modify the value as shown below.

 

curl -X

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

Rename the primaryVlanCTag to 555.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "555",

  "primaryVlanCtag": :555555"
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

  

 


body: 
IC-LAYER2-402: S-Tag Range
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause The value passed for Primary S-Tag exceeds the configured limit of characters.
Quick Fix Verify the Primary S-Tag value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "Range: Primary STag must be between 2 and 4094"
PROPERTY:   "primaryVlanSTag"

 

Verify the length of the primaryVlanSTag and modify the value as shown below.

 

curl -X

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

Rename the primaryVlanSTag to 555.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "55555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 

 


body: 
IC-LAYER2-402: Invalid Port ID
Code IC - LAYER2 - 402
Description Invalid request.
Generic Cause The value passed for primaryPortUUID doesn't match with the primaryPortUUID criteria.
Quick Fix Verify the primaryPortUUID value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-402"
MESSAGE:    "Invalid Request"

MOREINFO:   "For input string: \"30ac195544cexxx\"
PROPERTY:   "primaryPortUUID"

 

Verify the primaryportUUID and modify the value as shown below.

 

curl -X

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

Rename the primaryportuuid to 7e7374c4-a357-3570-f2e0-30ac195544ce.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544cexxxx",
  "primaryVlanSTag": "555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 

IC-LAYER2-4023

Code IC - LAYER2 - 4023
Description Connection error.
Generic Cause The value passed as connection ID does not exist or does not belong to the user.
Quick Fix Verify the connection ID passed in the URL.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-4023"
MESSAGE:    "Connection does not exist or do not belong to user,Please check connection Id"

MOREINFO:   ""
PROPERTY:   "uuid"

 

Verify the connection ID  passed in the URL and modify the value as shown below.

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/connections/97d1850f-4df0-468c-9281-fa7b0dfa2096" 

The endpoint URL is incorrect. Replace the ID with the correct ID.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

 


body: 

IC-LAYER2-AUTH-006

Code IC - LAYER2 - AUTH - 006
Description Invalid request.
Generic Cause The given named tag has already been used in another connection.
Quick Fix Verify whether there is an existing connection with the given NamedTag associated with the given authorization/service key.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-AUTH-006"
MESSAGE:    "Error while validating Authorization Key, NamedTag already in use"

MOREINFO:   ""
PROPERTY:   "authorizationkey"

 

Verify the namedTag and modify the value as shown below.

 

curl -X

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

Rename the namedTag to another value such as "Public", "Microsoft", or "Manual".

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

  -d '{

  "primaryName": "johnDoePrimary",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "johnDoeSecondary",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]
}'

 


body: 

IC-LAYER2-AUTH-007

Code IC - LAYER2 - AUTH - 007
Description Invalid request.
Generic Cause The given authorization key is not associated with the given seller/destination metro.
Quick Fix Verify whether the given authorization key is permitted to create connections to the desired metro.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-AUTH-007"
MESSAGE:    "Authorization Key does not match the destination Metro. Please verify the Authorization key"

MOREINFO:   ""
PROPERTY:   "authorizationKey"

 

Verify the sellerMetroCode and modify the value as shown below.

 

curl -X

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

Use a SellerMetroCode associated with the given authorization key. 

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

  -d '{

  "primaryName": "johnDoePrimary",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "johnDoeSecondary",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]
}'

 


body: 

IC-LAYER2-DOT1Q-001

Code IC - LAYER2 - DOT1Q - 001
Description Invalid request.
Generic Cause Maximum number of connections reached for a given Microsoft service key.
Quick Fix Verify the number of connections under the authorization key and use another key.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-DOT1Q-001"
MESSAGE:    "Cannot create more than three Dot1Q connections for the given Authorization Key"

MOREINFO:   ""
PROPERTY:   "authorizationKey"

 

Verify the authorization key and modify the value as shown below.

 

curl -X

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

Use a different authorization key to create the connections. 

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

  -d '{

  "primaryName": "JohnDoe_Dot1q_Public",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",

  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "TestS110",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]

}' 

 


body: 

IC-LAYER2-PORTS-001:

Code IC - LAYER2 - PORTS - 001
Description Invalid request.
Generic Cause Incorrect port uuid has been passed.
Quick Fix Verify the primaryPortUUID passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-PORTS-001"
MESSAGE:    "Port does not exist or not belong to user"

MOREINFO:   ""
PROPERTY:   "primaryPortUUID"

 

Verify primaryPortUUID and modify the value as shown below.

 

curl -X

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

Add the correct portID.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544de",
  "primaryVlanSTag": "55555",

  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 

IC-LAYER2-PORTS-016:

Code IC - LAYER2 - PORTS - 016
Description Invalid request.
Generic Cause Different port types used.
Quick Fix Verify the secondary port ID passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-PORTS-016"
MESSAGE:    "Ports do not have same type (buyout/standard "

MOREINFO:   "Primary Buyout Port: Y Secondary Buyout Port: N"
PROPERTY:   "secondaryPortUUID"

 

Verify secondaryPortUUID and modify the value as shown below.

 

Pass the correct secondary port ID.

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryName": "JohnDoe_Dot1q_Private",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "TestS110",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]

}

 


body: 

IC-LAYER2-REMOTE-003:

Code IC - LAYER2 - REMOTE - 003
Description Invalid request.
Generic Cause Invalid metro code passed.
Quick Fix Verify and pass the correct metro code.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-REMOTE-003"
MESSAGE:    "Metros are not remotely connected"

MOREINFO:   ""
PROPERTY:   "sellerMetroCode"

 

Verify whether the correct seller metrocode is used and modify the value as shown below.

 

The endpoint URL is incorrect 

curl -X

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

Rename the sellerMetroCode from "SL" to "SV".

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "55555",

  "namedTag": "Manual",
  "sellerMetroCode": "SL"
}'


body: 

IC-LAYER2-TAGS-001

Code IC - LAYER2 - TAGS- 001
Description Invalid request.
Generic Cause The given namedTag is not associated with the peering type.
Quick Fix Verify whether the coorect namedTag is passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-AUTH-007"
MESSAGE:    "Given namedTag doesn't match with seller named tag"

MOREINFO:   ""
PROPERTY:   "namedTag"

 

Verify the namedTag and modify the value as shown below.

 

curl -X

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

Replace "microsoft" with "Microsoft".

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

  -d '{

  "primaryName": "johnDoePrimary",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "johnDoeSecondary",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "microsoft",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
    "notifications": [
    "JohnDoe@equinix.com"
  ]
}'

 


body: 

IC-LAYER2-VLAN-005:

Code IC - LAYER2 - VLAN - 005
Description Invalid request.
Generic Cause Invalid or inapplicable tagging information sent in request payload.
Quick Fix Remove Primary C-Tag from the request payload. 

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-VLAN-005"
MESSAGE:    "Vlan Inner tag not required"

MOREINFO:   ""
PROPERTY:   "primaryVlanCTag"

 

Verify whether a primaryVlanCTag is sent and remove the field as shown below.

 

The endpoint URL is incorrect 

curl -X

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

Remove primaryVlanCTag as its inapplicable.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{
  "primaryName": "JohnDoe_Demo_Connection",
  "profileUUID": "937d83b1-ce02-452e-b60b-80955eb91c",
  "speed": 50,
  "speedUnit": "MB",
  "notifications": [
    "john.doe@demo.com"
  ],
  "purchaseOrderNumber": "1234567890",
  "primaryPortUUID": "7e7374c4-a357-3570-f2e0-30ac195544ce",
  "primaryVlanSTag": "55555",

  "primaryVlanCTag": "55555",
  "namedTag": "Manual",
  "sellerMetroCode": "SV"
}'

 


body: 

IC-LAYER2-VLAN-007:

Code IC - LAYER2 - VLAN - 007
Description Invalid request.
Generic Cause Missing VLAN tagging information in the request payload.
Quick Fix Add Primary C-Tag for the request payload. 

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-VLAN-007"
MESSAGE:    "Vlan Inner tag required"

MOREINFO:   ""
PROPERTY:   "primaryVlanCTag"

 

Verify whether a primaryVlanCTag is added as shown below.

 

Add the missing primaryVlanCTag

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "primaryName": "JohnDoeOracleQinQ",
  "profileUUID": "c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8",
  "speed": 1,
  "speedUnit": "GB",
  "notifications": [
    "JohnDoe@equinix.com"
  ],
  "purchaseOrderNumber": "1111",
  "primaryPortUUID": "7f891e3b-974f-74f0-bae0-30ec1885143a",
  "primaryVlanSTag": "3273",
  "primaryVlanCTag": "1111",
  "sellerRegion": "us-ashburn-1",
  "sellerMetroCode": "DC",
  "authorizationKey": "ocid1.virtualcircuit.oc1.iad.aaaaabcdp2mwua7njveex3vmhchwqwyzzka5zrrhbo4wc7uz46pzlqghkzgq"
}'

 


body: 

IC-LAYER2-VLAN-008:

Code IC - LAYER2 - VLAN - 008
Description Connection error.
Generic Cause Duplicate VLAN ID argument passed to the method. 
Quick Fix Verify and rename the VLAN ID value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-VLAN-008"
MESSAGE:    "Connection has duplicate buyer-side VLAN ID for primary port or the same VLAN ID is the process of being deleted and should be freed up soon"

MOREINFO:   ""
PROPERTY:   "PrimaryVlanStag"

 

Verify the primary VLAN tag and modify the value as shown below.

 

curl -X

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

Rename the primary VLAN S-Tag with a different Tag.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{

  "primaryName": "johnDoePrimary",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "johnDoeSecondary",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
  "notifications": [
  "JohnDoe@equinix.com"
  ]
}'

 


body: 

IC-LAYER2-VLAN-009:

Code IC - LAYER2 - VLAN - 009
Description Connection error.
Generic Cause Duplicate secondary VLAN ID argument passed to the method. 
Quick Fix Verify and rename the secondary VLAN ID value passed.

 

    Error scenario example

ERROR   

CODE:       "IC-LAYER2-VLAN-009"
MESSAGE:    "Connection has duplicate buyer-side VLAN ID for secondary port or the same VLAN ID is the process of being deleted and should be freed up soon"

MOREINFO:   ""
PROPERTY:   "SecondaryVlanStag"

 

Verify the secondary VLAN tag and modify the value as shown below.

 

curl -X

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

Rename the secondary VLAN S-Tag with another Tag ID.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

-d '{

  "primaryName": "johnDoePrimary",
  "profileUUID": "84c6616c-573a-447d-a478-9fab8fff284d",
  "speed": 50,
  "speedUnit": "MB",
  "purchaseOrderNumber": "",
  "primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
  "primaryVlanSTag": "458",
  "secondaryName": "johnDoeSecondary",
  "secondaryVlanSTag": "442",
  "secondaryPortUUID": "7f891d3b-9740-7400-bae0-30ac1885197a",
  "namedTag": "Private",
  "sellerMetroCode": "SV",
  "authorizationKey": "76e781b5-2992-4042-b2a2-37d0d5eb6735",
  "notifications": [
  "JohnDoe@equinix.com"
  ]
}'

 


body: 

415: Unsupported media type 

The 415 (Unsupported media type) status code indicates that the request has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.

 

 

Code 415
Description Unsupported media type.
Generic Cause Server is refusing to service the request because the payload is in a format not supported by this method on the target resource.
Quick Fix Verify request payload.

 


body: 

401: Unauthorized

The 401 (Unauthorized) status code indicates that the authentication credentials received are not authorized. The user may repeat the request with a new or replaced Authorization header field. 

 

Code 401
Description Authentication Error.
Generic Cause Unauthorized authentication token.
Quick Fix Verify whether an authentication token is obtained and ensure to provide this with each request.

 

There are different types of Authentication errors and this section provides sample scenarios of authentication errors as well as tips on how to identify them.

 


body: 

404: Resource not found 

The 404 (Resource not found) status code indicates that the server cannot find the requested resource but may be available in the future.

 

Code 404
Description Resource not found.
Generic Cause Resource is invalid or unavailable.
Quick Fix Verify end-point URL and resource info.

 

 


body: 

404 - Invalid Endpoint

Code 404
Description Invalid Endpoint.
Generic Cause Invalid API path in payload.
Quick Fix Verify the end-point information submitted.

 

   Error scenario example

ERROR   

CODE:       "404"
MESSAGE:    "Not Found - No message available"

PATH        "/ecx/v3/l2/common/metro"

TIMESTAMP   "1544951546619"

 

Verify end-point URL.

 

The end-point URL is incorrect. Replace endpoint metro with metros.

curl -X
GET "https://api.equinix.com/ecx/v3/l2/common/metro"

-H "accept: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 


body: 

IC-PROFILE-404: 

Code IC - PROFILE- 404
Description Invalid service profile.
Generic Cause Connection ID does not exist or does not belong to the user.
Quick Fix Verify the connection ID passed in the URL.

 

    Error scenario example

ERROR   

CODE:       "IC-PROFILE-404"
MESSAGE:    "Service profile not found in database"

MOREINFO:   ""
PROPERTY:   "uuid"

 

Verify the connection ID  passed in the URL. Identify and modify the value accordingly.

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/connections/97d1850f-4df0-468c-9281-fa7b0dfa2096" 

The endpoint URL is incorrect.Replace the ID with the correct ID.

-H "Content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"  

 


body: 

500: Internal Server Error 

The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

 

Code 500
Description Internal server error.
Generic Cause System encountered an unexpected problem and is being tracked.
Quick Fix Try again or or post the issue on our forum or contact api-support@equinix.com.

 


body: 

500- ERR-L2-001-08

Code 500 - ERR-L2-001-08
Description Validation Error.
Generic Cause Invalid operation on endpoint.
Quick Fix Verify the operation performed on the end-point.

 

    Error scenario example

ERROR   

CODE:       "ERR-L2-001-08"
MESSAGE:    "Method not supported,Please check the URL passed"

MOREINFO:   "method:POST"

 

Verify operation performed on end-point URL, (i.e.) POST, GET, DELETE etc. Modify the method as shown below.

 

The operation performed on the URL is incorrect. Replace POST with GET.

curl -X

POST "https://api.equinix.com/ecx/v3/l2/common/metros"
-H "Content-type: application/json"
-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

 


body: 

S1002: Unable to process the Request

Error Code

S1002

Description

Authentication error.

Generic Cause

Unable to obtain access token information due to a connectivity issue.
Quick Fix Try again or post the issue on our forum or contact api-support@equinix.com. 

 

    Error scenario example

ERROR Domain: Apps - FQA
ERROR Title: "Unable to process the request"
CODE: "S1002"
DEVELOPER MESSAGE: "Execution of ServiceCallout PingCallout failed. Reason: timeout occurred PingCallout"
ERROR MESSAGE: "Unable to process the request, Please try again later"

 

Try calling the API again.

 

Retry calling the API URL.

curl -X

POST "https://api.equinix.com/oauth2/v1/token"   

-H "Content-type: application/json"

-d '{
  "user_password": "johndoe",
  "grant_type": "client_credentials",
  "user_name": "johndoe",
  "client_secret": "ZXYAbcdLMNOpQrst",
  "client_id": "O0079ABCDEFGHIJKLMNOpqrstuvwxyz"
} '

 


body: 

429: Too many request Error

The 429 (Too many requests) status code indicates that the user has sent too many requests in a given amount of time.

 

Code 429
Description Internal server error.
Generic Cause Request rejected due to rate limiting (number of requests exceeded for the given time).
Quick Fix Try again later or post the issue on our forum or contact api-support@equinix.com .

 


body: 

503: Service unavailable

The 503 (Service unavailable) status code indicates that the server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

 

Code 503
Description Service unavailable.
Generic Cause Service unavailable due to temporary overload or scheduled maintenance and is likely be alleviated after some delay.
Quick Fix Try again or post the issue on our forum or contact api-support@equinix.com.
 

 


body: 

Don't Like Reading?


body: 

How about a 1-minute video? 

Equinix Cloud Exchange Fabric Overview

 

 

Calling OAuth API

 

 


body: 

Take a shot at our forum

Equinix Cloud Exchange Forum

 


body: 

Glossary

 

Access Token

A credential used to communicate with the API.

Cage

A custom build (as per customer’s requirement) and secured mesh enclosure to house multiple cabinets in it.
Equinix Cloud Exchange Fabric or ECX Fabric or ECX Equinix Cloud Exchange Fabric (ECXF) is an advanced software-defined interconnection solution that enables you to directly, securely and dynamically connect to distributed infrastructure and digital ecosystems on platform Equinix via a single port.

IBX

Equinix International Business Exchange.

OAuth

 

OAuth (Open Authorization) is an open standard for token-based authentication and authorization on the Internet.

 

Rack

A physical enclosure to hold IT equipment, also called a Cabinet.

 

Refresh Token

 

A token that contains the information required to obtain a new Access Token.

 

 


body: 

Style guide and References

Additional information

 

 

Tips and recommendation 

 

 

Critical information 

 

 

Code snippet

 

 

Output snippet 

 

 

Error information

 

 

Internal Links

 

External Links

 

References Links
AWS AWS icons
Azure Azure logo
Google Google icons    Google logo
Oracle Oracle logo

 


body: 

 

 

 Contact us

If you have any questions or comments regarding Equinix APIs, please contact api-support@equinix.com


Twitter Feed

About Equinix

Equinix connects the world's leading businesses to their customers, employees and partners inside the world's most connected data centers in 44 markets across five continents. In the United States, Equinix operates data centers in Atlanta, Boston, Chicago, Dallas, Denver, Los Angeles, Miami, New York, Philadelphia, Seattle, Silicon Valley and Washington D.C.

Developer Platform - Key Highlights

  • Explore, Subscribe & Connect to Equinix API Ecosystem​
  • Test Drive Equinix APIs using our Playground
  • Start your journey with Getting Started Guide

Recent News

IBX SmartView Streaming API is now available on Developer Platform
Equinix Customer Portal APIs (Beta) is now available on Playground.
ECX Fabric v3 API is recommended for integration.
New Developer Experience Launched! Let us know your feedback.
You can download the API catalog now in PDF or JSON or HTML or YAML
 
Copyright © 2018 Equinix. All rights reserved. Terms of Use | Privacy Policy | API Agreement