https://developer.equinix.com
  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 customer is onboarded, they are provided with user credentials. 

 

 

The customer must use these credentials to connect to the Equinix Developer Platform to generate a Consumer key and Consumer secret, also known as client ID and client 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 OAuth2 access token to the API gateway.

 

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

 

API Request flow:

Step 6  - The customer 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 customer.

 

Step 10  - Customer 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 APIs.

 


body: 

Generating Client ID and Client Secret key

To obtain your client ID (consumer key) and client secret key (consumer secret), you must register your app in the developer platform according to your preferred environment. 

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 Create New App button.

 

 

4. You will need to name your app and then select the app type to be used, you can either create an app for the Sandbox or Production environment. Once you’re ready click on the Create App button.

 

The sandbox environment is only a test environment that mimics the production environment and creates simulated API responses. 

If you are not an existing API customer, send an email to api-support@equinix.com to gain access to Equinix sandbox.

 

 

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 can obtain your access token by either using the password or client credentials grant type as shown in the sample curl commands below:

 

The client_credentials grant type is used by users who do not want to use their Equinix login credentials (user name and user password) in exchange for an access token, whereas the password grant type is for users who are less hesitant. 

 

Refer to https://oauth.net/2/grant-types/ for more information about the different grant types and their usage. 

 

Access token using password grant type

 

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"

}'

 

Access token using client credentials grant type  (Recommended)

 

curl -X

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

-H "content-type: application/json"

-d '{

"grant_type": "client_credentials",

"client_id": "ABCDE12345",

"client_secret": "FGHIJ67890"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
grant_type Yes string password

"password"

"client_credentials"

 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 Equinix login username. This field is optional for client credentials grant type.
user_password Yes string jd1@#$   The Equinix login password. This field is optional for client credentials grant type.
client_id Yes string ABCDE12345   A special ID generated by the Equinix Developer Platform.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer Platform.
password_encoding No string md5-b64 "md5-b64"

An optional field for users who wish to encrypt their password when requesting an access token. Currently, only “md5-b64” hashing is supported. This field is only applicable to users who use password grant. 

 

 

Click here to learn how to encrypt your password using md5-b64 hashing.

 

 

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, the respective token and timeout details will be sent to you as shown in the sample JSON responses below.

 

Sample response when using password grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

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

    "token_type": "Bearer",

    "refresh_token": "zxcvbn1JKLMNOPQRSTU",

    "refresh_token_timeout": "5184000"

}

 

Refresh token details will only be sent to customers that use password grant.

 

Sample response when using client credentials grant type

 

{

    "access_token": "qwErtY8zyW1abcdefGHI",

    "token_timeout": "3600",

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

    "token_type": "Bearer",

}

 

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 Equinix login username.
token_type string Bearer

"Bearer"

 The type of token. 
refresh_token string zxcvbn1JKLMNOPQRSTU   Access tokens have limited lifetimes. If your application needs access to an 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. This information is only applicable to "password" grant users. 
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. This information is only applicable to "password" grant users.

 

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 Platform.
client_secret Yes string FGHIJ67890   A special key generated by the Equinix Developer Platform.
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"

}

 

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.

 


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. 

 

Click here to download the postman scripts and watch a video on how to connect to AWS Direct Connect using Equinix Cloud Exchange Fabric APIs. 

 


body: 
How to establish a layer 2 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 the 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 port details. You may skip this step if you already know your port information.

 

2c) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.  

 

2d) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether your AWS Account Info can be used to create a connection to the seller profile selected earlier.

 

The validate authorization key API currently only performs regular expression validation and checks if a connection can be established to the selected seller service profile. It does not validate the authenticity and accuracy of the key against AWS. This feature will be included in the future.

 

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 Direct Connect connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

AWS Direct Connect 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 Direct Connect 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's primary port from which the connection would 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 to be allocated to the connection.
speedUnit Yes string MB MB Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array [string] JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
sellerRegion Yes string us-west-1   The region in which the seller port resides.
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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}

 

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.

 

These status values will only be reflected after the below "Accept Connection" step is performed. 

 

 

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

 

 

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

 DEPROVISIONING

Connection disbandment in progress.
DEPROVISIONED DEPROVISIONED

Connection deleted.

 


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 The status message of the PATCH API call.
primaryConnectionID string primaryConnectionId: "9999a8-0e07-44d0-944c-88a25d8d28f7" 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 Microsoft

End users can create connections to Azure Express Route using either a Dot1q port or a QinQ port. 

 

Click here to download the postman scripts and watch a video on how to connect to Azure Express Route using Equinix Cloud Exchange Fabric Portal. 

 


body: 
How to establish a layer 2 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 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 port details. You may skip this step if you already know your port information.

 

2c) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information. 

 

2d) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether your Azure service key can be used to create a connection to 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 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,  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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices.

 

Azure Express Route 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 Express Route 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's primary port from which the connection would 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 to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array  JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
sellerMetroCode Yes string DC   The metro code that denotes the connection’s destination (Z side). 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's secondary port from which the secondary connection would 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 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}.

Should you want to upgrade the speed/bandwidth of this connection, you can use the PATCH API /ecx/v3/l2/connections/{connId}.

 

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
PROVISIONING NOT_AVAILABLE Not provisioned Not provisioned   Connection request has not been yet sent to Microsoft Azure.
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.

 

 

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.
PROVISIONING  PROVISIONED Provisioned Provisioned Provisioning completed at Microsoft's end and the connection is provisioning at Equinix's end.
PROVISIONED PROVISIONED Provisioned Provisioned The connection is provisioned.
 

 

Refer https://docs.microsoft.com/en-us/azure/expressroute/expressroute-howto-circuit-portal-resource-manager for the different Azure Express Route states.  

 

 

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

 PROVISIONED

Connection disbandment in progress.
DEPROVISIONED DEPROVISIONED

Connection deleted.

 


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 GCPI  using either a Dot1q port or a QinQ port. 

 

Click here to download the postman scripts and watch a video on how to connect to GCPI using Equinix Cloud Exchange Fabric APIs. 

 


body: 
How to establish a layer 2 connection to Google Cloud Partner Interconnect?
 

 


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 with zone 1 seller/service profile.

 

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 the 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 port details. You may skip this step if you already know your port information.

 

2c) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.  

 

2d) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether your Google pairing key can be used to create a connection to the seller profile selected earlier.

 

The validate authorization key API currently only performs regular expression validation and checks if a connection can be established to the seller service profile. It will include validation of the pairing key with Google in the future.

 

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 GCPI connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

GCPI 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"

}'

 

GCPI 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's primary port from which the connection would 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 to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
sellerRegion Yes string us-west-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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}

Should you want to upgrade the speed/bandwidth of this connection, you can use the PATCH API /ecx/v3/l2/connections/{connId}.

 

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 GCPI State Description
PROVISIONING NOT_AVAILABLE   Connection request has not been yet sent to Google.
PROVISIONED PENDING_APPROVAL 

Waiting for service provider

The connection awaits for acceptance.
PROVISIONED 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.  

 

 

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

 DEPROVISIONING

Connection disbandment in progress.

 
DEPROVISIONED DEPROVISIONED

Connection deleted.

 


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. 

 

Click here to download the postman scripts and watch a video on how to connect to Oracle FastConnect using Equinix Cloud Exchange Fabric APIs. 

 


body: 
How to establish a layer 2 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 the 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 port details. You may skip this step if you already know your port information.

 

2c) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.  

 

2d) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether your Oracle OCID can be used to create a connection to 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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices.

 

Oracle FastConnect 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 FastConnect 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's primary port from which the connection would 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 to be allocated to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the OCID to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth to be allocated to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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   The region in which the seller port resides.
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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 GET API /ecx/v3/l2/connections/{connId}

Should you want to upgrade the speed/bandwidth of this connection, you can use the PATCH API /ecx/v3/l2/connections/{connId}.

 

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

Connection awaits for acceptance. Connection establishment in progress.
PROVISIONED PROVISIONED 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

 DEPROVISIONING

Connection disbandment in progress.
DEPROVISIONED DEPROVISIONED

Connection deleted.

 

 


body: 

Connect to Oracle Government Cloud

End users can create connections to Oracle Government Cloud FastConnect using either a Dot1q port or a QinQ port. 

 

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

 


body: 
How to establish a layer 2 connection to Oracle Government Cloud 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 Government Cloud FastConnect connection. 

 

Refer to https://www.oracle.com/industries/public-sector/government-cloud/ for instructions on how to signup for Oracle Government Cloud. 

 


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 port details. You may skip this step if you already know the available port information.

 

2c) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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.  

 

2d) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. You may skip this step if you already know the service profile details.

 

2e) Get ValidateAuthorizationKey

Verify whether your Oracle OCID can be used to create a connection to 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 key, refer to Requesting Access and Refresh tokens section under Getting Started.

 

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

 

Oracle Government Cloud FastConnect 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.oc2.us-langley-1.aaaaafzx4jybgymnyfjfwyxl7f4b6emvxzp2lqcnpjq"
}'

 

Oracle Government Cloud FastConnect 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": "774",
  "primaryVlanCTag": "775",
  "sellerRegion": "us-ashburn-1",
  "sellerMetroCode": "DC",
  "authorizationKey": "ocid1.virtualcircuit.oc2.us-langley-1.aaaaafzx4jybgymnyfjsdfsdgdfgeryterylqcnpjq"
}'

 

 

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 9f891d3b-973c-73c0-bae0-30ac1885197a   Unique identifier of the buyer's primary port from which the connection would 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 c7f5469b-9618-4d8e-b7dc-9e643rd0a8b8  

Unique identifier of the provider's service profile. 

 

Ensure that you are connecting to the "Oracle Cloud Infrastructure Government Layer 2" profile.
authorizationKey Yes string ocid1.virtualcircuit.oc2.us-langley-1.aaaaafzx4jybgymnyfjsdfsdgdfgeryterylqcnpjq   Authorization Key obtained from the provider. For example, OCID from Oracle Cloud Infrastructure.
speed Yes integer 50   Speed/Bandwidth to be allocated to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the authorization key to obtain the speed.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 1111   An optional field to link the purchase order numbers to the connection on Equinix which would be reflected on the invoice.
sellerRegion Yes string us-ashburn-1   The region in which the seller port resides.
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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}

Should you want to upgrade the speed/bandwidth of this connection, you can use the PATCH API /ecx/v3/l2/connections/{connId}.

 

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.

 

 

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 DEPROVISIONING Connection disbandment in progress.
DEPROVISIONED DEPROVISIONED

Connection deleted.

 


body: 

Connect to IBM

End users can create connections to IBM Direct Link using either a Dot1q port or a QinQ port. 

 

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

 


body: 
How to establish a layer 2 connection to IBM?

 

 


body: 
Step 1: Retrieve IBM Account Info

Locate your IBM account ID using the IBM cloud portal.

 

The IBM Account ID is essential for creating an IBM Direct Link connection.

 

Refer https://www.ibm.com/cloud/direct-link/details for instructions on how to signup for IBM Direct Link. 

 


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) 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, additionalInfo[...]

 

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 IBM connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

IBM 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_IBM_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",
  "additionalInfo": [
    {
      "name": "global",
      "value": true
    },
    {
      "name": "asn",
      "value": "1543"
    }
  ],
  "authorizationKey": "1956030"
}'

 

IBM 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_IBM_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", 

  "additionalInfo": [
    {
      "name": "global",
      "value": true
    },
    {
      "name": "asn",
      "value": "1543"
    }
  ],
  "authorizationKey": "1956030"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
primaryName Yes string JohnDoe_IBM_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's primary port from which the connection would 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: Service Key from IBM.
speed Yes integer 50   Speed/Bandwidth to be allocated to the connection.
speedUnit Yes string MB MB Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array[string] JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
sellerRegion Yes string us-west-1   The region in which the seller port resides.
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 
additionalInfo Yes array[string]     An array containing additional information.
name Yes string global  

Indicates whether it's a global or local data center and whether the routing is done locally or globally.

 

Refer to  https://cloud.ibm.com/docs/direct-link?topic=direct-link-faqs for more info

 
value Yes boolean true

true

false

 Indicates whether it's globally available in IBM.
name Yes string asn   Customer BGP ASN.
value Yes integer 1543   The value of the customer BGP ASN value.

 

The following table indicates the tagging criteria to be followed when a buyer/customer (A-side) wants to connect to IBM (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}

 

When a connection is created, the connection transitions through various states within the Equinix and IBM 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 IBM.

 

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

Create approval pending

The connection awaits for approval.
The connection must be approved or rejected at IBM's end at this point or the "status" and "providerStatus" would remain unchanged.
PROVISIONING PROVISIONING / PROVISIONED Create in progress Connection establishment in progress.
PROVISIONED PROVISIONED Provisioned

The connection has been established.

 

Refer https://www.ibm.com/cloud/direct-link/details for the different IBM connection states.  

 

 

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 IBM Direct Link State Description

DEPROVISIONING

 DEPROVISIONING Delete Approval Pending

Connection disbandment in progress.

 
The delete request must be approved at the IBM's end 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.
DEPROVISIONED DEPROVISIONED  

Connection deleted.

 


body: 
Step 3: Accept Connection

Accept the virtual connection using IBM Direct Link portal

 

Refer to https://www.ibm.com/cloud/direct-link/details for instructions on how to accept the connection using IBM Direct Link portal.

 


body: 

Connect to Alibaba

End users can create connections to Alibaba Express Connect using either a Dot1q port or a QinQ port. 

 

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

 


body: 
How to establish a layer 2 connection to Alibaba?

 

 


body: 
Step 1: Retrieve Alibaba Cloud Account Info

Locate your Alibaba Cloud Account ID using the Alibaba Cloud console.

 

The Alibaba Account ID is essential for creating an Alibaba Express Connect connection.

 

Refer https://www.alibabacloud.com/help/product/27782.htm?spm=a3c0i.intl-en-product-expressconnect.0.0.438b6fae0T5ls9 for instructions on how to signup for Alibaba Express Connect. 

 


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) 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, additionalInfo[...]

 

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 Express Connect connection using a Dot1q and QinQ port and a sample JSON response for this API. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

Alibaba Express Connect 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_Alibaba_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": "1956030"
}'

 

Alibaba Express Connect 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_Alibaba_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": "1956030"

}'

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
primaryName Yes string JohnDoe_Alibaba_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's primary port from which the connection would 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 Alibaba.
speed Yes integer 50   Speed/Bandwidth to be allocated to the connection.
speedUnit Yes string MB MB Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array[string] JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
sellerRegion Yes string us-west-1   The region in which the seller port resides.
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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 Alibaba (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}

 

When a connection is created, the connection transitions through various states within the Equinix and Alibaba 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 Alibaba.

 

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

Pending creation

The connection awaits for approval.
PROVISIONED PROVISIONING Create in progress Connection establishment in progress.
PROVISIONED PROVISIONED Active

The connection has been accepted by the client.

 

These status values will only be reflected after the below "Accept Connection" step is performed.

 

 

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

 DEPROVISIONING

Connection disbandment in progress.

 
DEPROVISIONED DEPROVISIONED

Connection deleted.

 


body: 
Step 3: Accept Connection

Accept the virtual connection using Alibaba Cloud Console.

 

Refer to https://www.alibabacloud.com/help/product/27782.htm?spm=a3c0i.intl-en-product-expressconnect.0.0.438b6faeZ3xOjUt for instructions on how to accept the connection using Alibaba Cloud Console.

 


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 a layer 2 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 the 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 port details. You may skip this step if you already know your port information.

 

2b) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.  

 

2c) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

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 retrieve service profiles in ECXF. 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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices.

 

Non-Redundant Connection from a Dot1q port to a service profile with 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_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 "https://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 "https://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 "https://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's primary port from which the connection would 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 to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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 GET API /ecx/v3/l2/connections/{connId}

Should you want to upgrade the speed/bandwidth of this connection, you can use the PATCH 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 a layer 2 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 the 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 port details. You may skip this step if you already know your port information.

 

2b) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.

 

2c) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

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 retrieve service profiles in ECXF. 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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

Redundant Connection from a Dot1Q port to a service profile with 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_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 "https://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 "https://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 "https://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's primary port from which the connection would 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 to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array  johnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string DC   The metro code that denotes the connection’s destination (Z side). 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. It indicates the region in which the seller port resides.
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's secondary port from which the secondary connection would 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 a layer 2 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 the 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 port details. You may skip this step if you already know your port information.

 

2b) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.  

 

2c) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. 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, 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 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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

Non-Redundant Connection from a Dot1q port to 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_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 "https://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 "https://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 "https://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's primary port from which the connection would 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 to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth to be allocated to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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 a layer 2 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 the 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 port details. You may skip this step if you already know your port information.

 

2b) Get Metros

Find all metros where ECXF is available to check if a connection can be established between the port selected earlier and your desired destination metro.

 

Use this API to identify the metro codes of your source (A-side) and destination (Z-side) for your 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 this information.

 

2c) Get Service Profile

Identify all service profiles available for a given metro or metros, and select the profile to which you wish to connect.

 

Refer to GET Services under the API Reference section for instructions on how to retrieve service profiles in ECXF. 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, 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 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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

Redundant Connection from a Dot1Q port to 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_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 "https://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 "https://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 "https://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's primary port from which the connection would 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 to be allocated to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the authorization key to obtain the speed.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array  johnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string DC   The metro code that denotes the connection’s destination (Z side). 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's secondary port from which the secondary connection would 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: 
How to establish a layer 2 non-redundant port to port 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.  

 


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, 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 port. 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. 

 

Should you want to estimate the price of this connection, use the API /ecx/v3/l2/connections/prices

 

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",

  "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",

  "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",

  "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",

  "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's primary port from which the connection would 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.
speed Yes integer 50   Speed/Bandwidth to be allocated to the connection.
speedUnit Yes string MB   Unit of the speed/bandwidth to be allocated to the connection.
notifications Yes array string JohnDoe@equinix.com

 

 A list of email addresses that would be notified when there are any updates on this 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 be reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string SV   The metro code that denotes the connection’s destination (Z side). 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 create a service profile?

 

 


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: Create Seller Profile

POST /ecx/v3/l2/serviceprofiles
Method POST
URL or End Point /ecx/v3/l2/serviceprofiles
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters additionalBuyerInfo [{captureInEmail, datatype, description, mandatory, name }], alertPercentage, allowCustomSpeed, apiAvailable, authKeyLabel, connectionAccessibility, connectionNameLabel, ctagLabel, description, equinixManagedPortAndVlan, features {cloudReach, testProfile}, integrationId, namedTags[...], ports[{crossConnectId, id, inTrail, metroCode, sellerRegion, sellerRegionDescription, xa{}}], private, requiredRedundancy, speedBands[{speed, unit}], speedFromAPI, tagType, uuid, status, vlanSameAsPrimary, name, onBandwidthThresholdNotification[...], onProfileApprovalRejectNotification[...], onVcApprovalRejectionNotification[...], privateUserEmails[...]}

 

The POST connections API creates a Layer 2 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 service profile and a sample JSON response for this API. 

 

Private Profile

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "name": "JohnDoe_Private_ServiceProfile",
  "privateUserEmails": [],
  "onProfileApprovalRejectNotification": [
    "John.Doe@example.com"
  ],
  "onBandwidthThresholdNotification": [
    "John.Doe@example.com"
  ],
  "onVcApprovalRejectionNotification": [
    "John.Doe@example.com"
  ],
  "connectionNameLabel": "Connection",
  "ctagLabel": "",
  "equinixManagedPortAndVlan": false,
  "allowOverSubscription": false,
  "overSubscription": "",
  "apiAvailable": false,
  "integrationId": "",
  "private": true,
  "features": {
    "cloudReach": true,
    "testProfile": false
  },
  "requiredRedundancy": false,
  "tagType": null,
  "vlanSameAsPrimary": false,
  "enableAutoGenerateServiceKey": null,
  "additionalBuyerInfo": [],
  "ports": [
    {
      "id": "8cb83fdb-6651-6514-bbe0-38389cc0acfa",
      "metroCode": "SV"
    },
    {
      "id": "8cb83fdb-661d-61d4-bbe0-38389cc0acfa",
      "metroCode": "SV"
    }
  ],
  "allowCustomSpeed": false,
  "speedFromAPI": false,
  "speedBands": [
    {
      "speed": 50,
      "unit": "MB"
    },
    {
      "speed": 200,
      "unit": "MB"
    },
    {
      "speed": 500,
      "unit": "MB"
    },
    {
      "speed": 1000,
      "unit": "MB"
    }
  ]
}

 

Public Profile

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "name": "JohnDoe_ServiceProfile",
  "privateUserEmails": [],
  "onProfileApprovalRejectNotification": [
    "John.Doe@example.com"
  ],
  "onBandwidthThresholdNotification": [
    "John.Doe@example.com"
  ],
  "onVcApprovalRejectionNotification": [
    "John.Doe@example.com"
  ],
  "alertPercentage": "85",
  "authKeyLabel": "Authentication Secret Key",
  "connectionNameLabel": "Connection",
  "ctagLabel": "",
  "equinixManagedPortAndVlan": true,
  "allowOverSubscription": true,
  "overSubscription": "10x",
  "apiAvailable": true,
  "integrationId": "Direct-01",
  "private": false,
  "features": {
    "cloudReach": true,
    "testProfile": false
  },
  "requiredRedundancy": true,
  "tagType": "CTAGED",
  "vlanSameAsPrimary": true,
  "enableAutoGenerateServiceKey": false,
  "additionalBuyerInfo": [],
  "ports": [
    {
      "id": "8cb83fdb-6671-6714-bbe0-38389cc0acfa",
      "metroCode": "SV"
    }
  ],
  "allowCustomSpeed": false,
  "speedFromAPI": true

}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
name Yes string JohnDoe_ServiceProfile   Name of the service profile - An alpha-numeric 50 characters string which can include only hyphens and underscores ('-' & '_').
privateUserEmails No array [string]     An array of users email ids who have permission to access this service profile. 
onProfileApprovalRejectNotification Yes array [string] John.Doe@example.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"]
onBandwidthThresholdNotification Yes array [string] John.Doe@example.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"]
onVcApprovalRejectionNotification Yes array [string] John.Doe@example.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"]
alertPercentage Yes string 85   Specifies the port bandwidth threshold percentage. If the bandwidth limit is met or exceeded, an alert is sent to the seller.
authKeyLabel No string Authentication Secret Key   The Authentication Key service allows Service Providers with QinQ ports to accept groups of connections or VLANs from Dot1q port customers. This is similar to S-Tag/C-Tag capabilities
connectionNameLabel Yes string Connection   Name of the connection.
ctagLabel No string     C-Tag/Inner-Tag of the connection - A numeric character ranging from 2 to 4094.
equinixManagedPortAndVlan   boolean true   Only applicable if API available is set true. It indicates whether the port and VLAN details are managed by Equinix. 
allowOverSubscription Yes boolean true   Regardless of the utilization, the Equinix service will continue to add connections to your links until we reach the oversubscription limit. By selecting this service, you acknowledge that you will manage decisions on when to increase capacity on these links.
overSubscription No string 10x   You can set an alert for when a percentage of your profile has been sold. Service providers like to use this functionality to alert them when they need to add more ports or when they need to create a new service profile.
apiAvailable Yes boolean true   API integration allows you to complete connection provisioning in less than five minutes. Without API Integration, additional manual steps will be required and the provisioning will likely take longer
integrationId No string Direct-01  

Specifies the API integration ID that was provided to the customer during onboarding. You can validate your API integration ID using the validateIntegrationId API.

 

If you are unaware of your integration ID, contact your local Equinix Service Desk.
private Yes boolean 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 Yes string     Contains feature-related information such as cloudReach, testProfile.
cloudReach Yes boolean true   Indicates whether or not connections to this profile can be created from remote metros.
testProfile Yes boolean false   Indicates whether or not this profile can be used for test connections.
requiredRedundancy Yes boolean true   Specify if your connections require redundancy. If yes, then users need to create a secondary redundant connection.
tagType No string CTAGED   Specifies additional tagging information required by the seller profile.
vlanSameAsPrimary Yes boolean true   Indicates whether the VLAN ID of the secondary connection is the same as the primary connection. 
enableAutoGenerateServiceKey No boolean false   Indicates whether multiple connections can be created with the same authorization key to connect to this service profile after the first connection has been approved by the seller.
additionalBuyerInfo No array[string]    

An array containing a maximum of 10 custom fields used for gathering additional information.
ports Yes string    

Where will your service be available?

Choose the locations where your customers will be able to access your services. These locations will need at least one active port present in order to qualify as an available zone.
id Yes string 8cb83fdb-6671-6714-bbe0-38389cc0acfa   The ID of the port.
metroCode Yes string SV   The metro where the port resides.
allowCustomSpeed Yes boolean false   Allow customer to enter a custom speed
speedFromAPI Yes boolean true   Derive speed from an API call

 

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

 

{
    "uuid": "36bfb968-1e4b-4973-baa0-35d2904944de"

}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
uuid string 36bfb968-1e4b-4973-baa0-35d2904944de Indicates the ID of the service profile created.
 

 


body: 
How to approve or reject a 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: Retrieve connections and Identify ports

2a) Retrieve connections

Identify the incoming connection you wish to accept or reject.

 

Refer to Get Seller Connections under the API Reference section for instructions on how to get all the seller connections. You may skip this step if you already know the connection details.  

 

2b) Identify ports

Identify your ECXF port(s) you intend to assign to the incoming connection.

 

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

 


body: 
Step 3: Accept or Reject Connection

Accept or reject incoming virtual connections to seller profile using the below API.

 

Patch Connections

PATCH /ecx/v3/l2/connections
 Method  PATCH
 URL or End Point  /ecx/v3/l2/connections/{connId}
 Headers  Authorization, Content-Type
 Query Parameters  action
 Body Parameters  primaryPortUUID, primaryVlanSTag, primaryVlanCTag, secondaryPortUUID, secondaryVlanSTag,     secondaryVlanCTag, rejectComment

 

 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.

 

connID is an identifier unique for each connection. The connection ID would be represented as uuid in the response of the seller connections API. 

 

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 modify a layer 2 service profile and a sample JSON response for this API. 

 

curl -X

PATCH "http://api.equinix.com/ecx/v3/l2/connections/9b1da3b0-ea1d-4770-ae51-c794ffb23dbc?action=Approve

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryPortUUID": "754086e4-164d-64d0-84e0-30ac188c7c35",
  "primaryVlanSTag": "555"

}'

 

{
    "message": "Successfully Approved",
    "primaryConnectionId": "9b1da3b0-ea1d-4770-ae51-c794ffb23dbc"
}

 

curl -X

PATCH "http://api.equinix.com/ecx/v3/l2/connections/60bfd673-8fbc-4de9-be4b-176ad8f3e908?action=Reject

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "rejectComment": "JohnDoe rejected"

}'

 

{
    "message": "Action successfully performed",
    "primaryConnectionId": "60bfd673-8fbc-4de9-be4b-176ad8f3e908"
}

 

curl -X

PATCH "http://api.equinix.com/ecx/v3/l2/connections/9b1da3b0-ea1d-4770-ae51-c794ffb23dbc?action=Approve

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "primaryPortUUID": "7cb83fdb-6620-6204-bbe0-38389cc0acfa",

  "primaryVlanSTag": "779",

  "secondaryPortUUID": "7cb83fdb-663a-63a4-bbe0-38389cc0acfa",

  "secondaryVlanSTag": "780"

}'

 

{
    "message": "Successfully Approved",
    "moreInfo": "Redundant connection also approved",
    "primaryConnectionId": "b9fb8603-a0a0-4534-a03a-78f3c9126bb5",
    "secondaryConnectionId": "13f1b31a-855b-44ca-b30a-4322a4d3af0b"
}

 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
primaryPortUUID Yes string 754086e4-164d-64d0-84e0-30ac188c7c35   The z side port  ID to which the buyer would be connecting to. 
primaryVlanSTag Yes string 555   S tag information of the port.
primaryVlanCTag Yes string 555   C tag information of the port.
secondaryPortUUID Yes string 7cb83fdb-6620-6204-bbe0-38389cc0acfa   The secondary z side port  ID to which the buyer would be connecting to. 
secondaryVlanSTag Yes string 779   S tag information of the secondary port.
secondaryVlanCTag Yes string 780   C tag information of the secondary port.
rejectComment Yes string JohnDoe rejected   Comment indicating why the connection was rejected.

 

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

 

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 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the secondary connection ID.

 


body: 
How to authorize a buyer to access a private service profile?

 

 


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: Retrieve service profile

Identify the seller service profile you wish to update.

 

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: Update Seller Profile

PUT Seller Profile

PUT /ecx/v3/l2/serviceprofiles
Method PUT
URL or End Point /ecx/v3/l2/serviceprofiles
Headers Authorization, Content-Type
Query Parameters Not applicable
Body Parameters uuid, additionalBuyerInfo [{captureInEmail, datatype, description, mandatory, name }], alertPercentage, allowCustomSpeed, apiAvailable, authKeyLabel, connectionAccessibility, connectionNameLabel, ctagLabel, description, equinixManagedPortAndVlan, features {cloudReach, testProfile}, integrationId, namedTags[...], ports[{crossConnectId, id, inTrail, metroCode, sellerRegion, sellerRegionDescription, xa{}}], private, requiredRedundancy, speedBands[{speed, unit}], speedFromAPI, tagType, uuid, status, vlanSameAsPrimary, name, onBandwidthThresholdNotification[...], onProfileApprovalRejectNotification[...], onVcApprovalRejectionNotification[...], privateUserEmails[...]}

 

The PUT serviceprofiles API updates a Layer 2 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 and a sample JSON response to modify a layer 2 service profile to white list the user Jane Doe. 

 

curl -X

PUT "http://api.equinix.com/ecx/v3/l2/serviceprofiles"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

  "uuid": "36bfb968-1e4b-4973-baa0-35d2904944de",

  "name": "JohnDoe_ServiceProfile",

  "privateUserEmails": [
    "Jane.Doe@ap.example.com"
  ],
  "onProfileApprovalRejectNotification": [
    "John.Doe@example.com"
  ],
  "onBandwidthThresholdNotification": [
    "John.Doe@example.com"
  ],
  "onVcApprovalRejectionNotification": [
    "John.Doe@example.com"
  ],
  "connectionNameLabel": "Connection",
  "ctagLabel": "",
  "equinixManagedPortAndVlan": false,
  "allowOverSubscription": false,
  "overSubscription": "",
  "apiAvailable": false,
  "integrationId": "Direct-01",
  "private": false,
  "features": {
    "cloudReach": false,
    "testProfile": false
  },
  "requiredRedundancy": false,
  "tagType": "CTAGED",
  "vlanSameAsPrimary": false,
  "enableAutoGenerateServiceKey": false,
  "additionalBuyerInfo": [],
  "ports": [
    {
      "id": "8cb83fdb-6671-6714-bbe0-38389cc0acfa",
      "metroCode": "SV",

      "sellerRegion": null
    }
  ],
  "allowCustomSpeed": false,
  "speedFromAPI": false,

  "speedBands": [
    {
      "speed": 50,
      "unit": "MB"
    },
    {
      "speed": 200,
      "unit": "MB"
    },
    {
      "speed": 500,
      "unit": "MB"
    },
    {
      "speed": 1000,
      "unit": "MB"
    }
  ]

}

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example values Applicable values Description
uuid Yes string 9ac03fb0-339f-480e-a79e-87bae5ed0d75   The unique identifier of the service profile.
name Yes string JohnDoe_AWSServiceProfile   Name of the service profile - An alpha-numeric 50 characters string which can include only hyphens and underscores ('-' & '_').
privateUserEmails No array [string] Jane.Doe@example.com   An array of users email ids who have permission to access this service profile. 
onProfileApprovalRejectNotification Yes array [string] John.Doe@example.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"]
onBandwidthThresholdNotification Yes array [string] John.Doe@example.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"]
onVcApprovalRejectionNotification Yes array [string] John.Doe@example.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"]
alertPercentage Yes string 85   Specifies the port bandwidth threshold percentage. If the bandwidth limit is met or exceeded, an alert is sent to the seller.
authKeyLabel No string Authentication Secret Key   The Authentication Key service allows Service Providers with QinQ ports to accept groups of connections or VLANs from Dot1q port customers. This is similar to S-Tag/C-Tag capabilities
connectionNameLabel Yes string Connection   Name of the connection.
ctagLabel No string     C-Tag/Inner-Tag of the connection - A numeric character ranging from 2 to 4094.
equinixManagedPortAndVlan Yes boolean true   Only applicable if API available is set true. It indicates whether the port and VLAN details are managed by Equinix. 
allowOverSubscription Yes boolean true   Regardless of the utilization, the Equinix service will continue to add connections to your links until we reach the oversubscription limit. By selecting this service, you acknowledge that you will manage decisions on when to increase capacity on these links.
overSubscription No string 10x   You can set an alert for when a percentage of your profile has been sold. Service providers like to use this functionality to alert them when they need to add more ports or when they need to create a new service profile.
apiAvailable Yes boolean true   API integration allows you to complete connection provisioning in less than five minutes. Without API Integration, additional manual steps will be required and the provisioning will likely take longer
integrationId No string AWS-DirectConnect-01  

Specifies the API integration ID that was provided to the customer during onboarding.

You can validate your API integration ID using the validateIntegrationId API.

 

If you are unaware of your integration ID, contact your local Equinix Service Desk.
private Yes boolean 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 Yes object     Contains feature-related information such as cloudReach, testProfile.
cloudReach Yes boolean true   Indicates whether or not connections to this profile can be created from remote metros.
testProfile Yes boolean false   Indicates whether or not this profile can be used for test connections.
requiredRedundancy Yes boolean true   Specify if your connections require redundancy. If yes, then users need to create a secondary redundant connection.
tagType No string CTAGED   Specifies additional tagging information required by the seller profile.
vlanSameAsPrimary Yes boolean true   Indicates whether the VLAN ID of the secondary connection is the same as the primary connection. 
enableAutoGenerateServiceKey No boolean false   Indicates whether multiple connections can be created with the same authorization key to connect to this service profile after the first connection has been approved by the seller.
additionalBuyerInfo No array[string]    

An array containing a maximum of 10 custom fields used for gathering additional information.
ports Yes string    

Where will your service be available?

Choose the locations where your customers will be able to access your services. These locations will need at least one active port present in order to qualify as an available zone.
id Yes string 8cb83fdb-6671-6714-bbe0-38389cc0acfa   The ID of the port.
metroCode Yes string SV   The metro where the port resides.
allowCustomSpeed Yes boolean false   Allow customer to enter a custom speed
speedFromAPI Yes boolean true   Derive speed from an API call

 

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

 

{
    "uuid": "36bfb968-1e4b-4973-baa0-35d2904944de"

}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
uuid string 36bfb968-1e4b-4973-baa0-35d2904944de Indicates the ID of the service profile which was updated.

 


body: 
How to update the bandwidth/speed of a 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: Update bandwidth/speed

Update the speed of the connection using the below API.

 

PATCH Connections {uuid}

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

 /ecx/v3/l2/connections/{uuid}
 Headers  Authorization, Content-Type
 Query Parameters  action
 Body  speed, speedUnit

 

The connection speed can only be updated for Microsoft Azure, Oracle FastConnect, Google, and Enterprise connections.

 

Uuid is an identifier unique to 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 update the speed of a connection with UUID 9999a8-0e07-44d0-944c-88a25d8d28f7

 

curl -X

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

-H "content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

"speed":50,

"speedUnit":"MB"

}'

 

The description of the request payload is as follows:

 

URL Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string 9999a8-0e07-44d0-944c-88a25d8d28f7   The unique identifier of the connection.

 

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

"Approve"

"Reject"

"Update"

 The action to perform on the connection.

 

Body Parameter Name Mandatory Type Example Description
speed Yes integer 50 Speed/Bandwidth you would like to allocate to the connection
speedUnit Yes string MB Unit of the speed or bandwidth.

 

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

    "status": "submitted"
}

 

The description of the response payload is as follows:

 

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

 

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

 

In order for the speed to be updated, your seller must accept this request and make the relevant changes at the sellers' end. Once this is done, you can verify the speed using the GET API /ecx/v3/l2/connections/{connId}

 


body: 

V3 APIs Migration

What is ECXF  V3 APIs?

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

 

Why must you migrate to ECXF V3?

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

 

What are the unique capabilities of V3 APIs?

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

 



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

Inter-region and Inter-metro connections support

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

Private connectivity (Equinix Any-to-any)

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

Reseller Model Support

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

Yes

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

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

API support to create connections to IBM DirectLink

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

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

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

Get all inventory by port name

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

Enhanced Inventory Retrieval Options

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

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

 No No

Yes

External APIs for Quoting and Pricing

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

Get Port Utilization Stats

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

Named tags and custom Manual C-tag support*

 Support for naming of c-tags No No Yes

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

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

Connection deletion confirmation/approval

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

Set port Threshold

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

 

 

How complex is this migration?

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

 

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

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

 

Usecase 1: Create a layer 2 connection to AWS

Step 1: Retrieve AWS Account ID

 

Step 2: Get user port information  

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

Step 3: Get metro details

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

Step 4: Get service profile details

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

Step 5: Post connection request

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

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

}'

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

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

 

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

 

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

 

Step 6: Accept connection

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

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

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

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

 

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

 

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

 

Usecase 2: Create a layer 2 connection to Azure

Step 1: Retrieve Microsoft Service Key

 

Step 2: Get user port information  

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

Step 3: Get metro details

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

Step 4: Get service profile details

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

Step 5: Post connection request

 

V2 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

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

 

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

 

V3 request and response

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

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

 

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

 

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

 

Step 6: Setup Microsoft peering

 

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

 


body: 

API Reference

GET Methods

/ecx/v3/port/userport
/ecx/v3/l2/common/metros

L2 Buyer APIs​
/ecx/v3/l2/serviceprofiles/services
/ecx/v3/l2/serviceprofiles/services/{uuid}
/ecx/v3/l2/buyer/connections
/ecx/v3/l2/connections/validateAuthorizationKey
/ecx/v3/l2/connections/{uuid} 

L2 Seller APIs​ 
/ecx/v3/l2/seller/connections
/ecx/v3/l2/serviceprofiles 
/ecx/v3/l2/serviceprofiles/{uuid}
/ecx/v3/l2/serviceprofiles/validateIntegrationId/{integrationId}

 

POST Methods

L2 Buyer APIs
/ecx/v3/l2/connections 

L2 Seller APIs
/ecx/v3/l2/serviceprofiles

 

PATCH Methods

L2 Buyer and Seller APIs
/ecx/v3/l2/connections/{connID}

 

PUT Methods

L2 Seller APIs
/ecx/v3/l2/serviceprofiles

 

DELETE Methods


body: 

Layer 2 Buyer APIs (V2-Deprecated)


body: 

GET Ports

Note: This API has been deprecated and replaced by GET /ecx/v3/port/userport. Refer to GET userport under the API Reference section for more information.

 

GET /v2/ports
 Method  GET
 URL or End Point  /ecx/v2/ports
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The ports API returns the 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 all designated ports, and its respective JSON response containing the port information.

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

Pay attention to the metroCode attribute received in the response, as this indicates where the connection would be established from. This can be cross-referenced with the response from /ecx/v2/metros API to discover all the available metros where the user can connect to.

 

The description of the response payload is as follows:

 

Field Name Type Example Description
ports array [string]   An array containing multiple port information.
name string JohnDoePort The name assigned to the port.
bandwidths array

10 G

An array containing the supported port bandwidths.
is_buyout string

N

 Indicates whether the port is a buyout port. If the value is "Y", then it is an unlimited connections port that allows multiple connections on the port at no additional charge. If the value is "N" then it is a standard port.
ibx_name string DC5 The IBX in which the port resides.
layer3 string Y Indicates whether the port supports layer 3 connections.
metro_code boolean

DC

 The metro code where the port resides.
metro_name string Ashburn The metro name where the port resides.
port_group string 1 The Group id/number of the device where the port resides.
port_priority string

Primary

 The priority of the device (Primary/secondary).
encapsulation string Dot1q The VLAN encapsulation of the port (Dot1q or QinQ).
cross_connect_ids string 2456963 Cross-connect ID associated with the port.

 

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

 


body: 

GET Ports {port_name}

Note: This API has been deprecated and replaced by GET /ecx/v3/port/userport. Refer to GET userport under the API Reference section for more information.

 

GET /v2/ports/{port_name}
 Method  GET
 URL or End Point  /ecx/v2/ports/{port_name}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The ports API returns the details of a given port name. 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 its JSON response to obtain the port details for the port name JohnDoeDemoPort. 

 

curl -X

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

-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
port_name Yes string JohnDoeDemoPort

 

 Name of the port owned by the user.
 

 

{
  "ports": [
    {
      "name": "JohnDoePort",
      "bandwidths": [
        "10 G"
      ],
      "is_buyout": "Y",
      "ibx_name": "SV4",
      "layer3": "Y",
      "metro_code": "SV",
      "metro_name": "Silicon Valley",
      "port_group": "1",
      "port_priority": "Primary",
      "encapsulation": "Dot1q",
      "cross_connect_ids": [
        "21063683-A"
      ]
    }
  ],
  "port_clusters": [
    [
      "John-Doe-SERVICES-SV4-CX-PRI-03"
    ]
  ]
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
ports array [string]   An array containing multiple port information.
name string JohnDoePort The name assigned to the port.
bandwidths array

10 G

An array containing the supported port bandwidths.
is_buyout string

N

 Indicates whether the port is a buyout port. If the value is "Y", then it is an unlimited connections port that allows multiple connections on the port at no additional charge. If the value is "N" then it is a standard port.
ibx_name string DC5 The IBX in which the port resides.
layer3 string Y Indicates whether the port supports layer 3 connections.
metro_code boolean

DC

 The metro code where the port resides.
metro_name string Ashburn The metro name where the port resides.
port_group string 1 The Group id/number of the device where the port resides.
port_priority string

Primary

 The priority of the device (Primary/secondary).
encapsulation string Dot1q The VLAN encapsulation of the port (Dot1q or QinQ).
cross_connect_ids string 2456963 Cross-connect ID associated with the port
port_clusters array [string] John-Doe-SERVICES-SV4-CX-PRI-03 An array containing the different ports associated with this port.

 

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

 


body: 

GET Metros

Note: This API has been deprecated and replaced by GET /ecx/v3/l2/common/metros. Refer to GET metros under the API Reference section for more information.

 

GET /v2/metros
 Method  GET
 URL or End Point  /ecx/v2/metros
 Headers  Authorization, Content-Type
 Query Parameters  cloud_exchange_enabled, port_availalable
 Body  Not applicable

 

The metros API returns all available metros with ECX 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), Warsaw (WA) and Zurich (ZH).

 

curl -X

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

-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
clooud_exchange_enabled No String  

true

false

 Used for filtering the results to get the metros where Cloud Exchange is enabled. If this parameter is not included the result will contain all the metros where the user has ports or Cloud Exchange is enabled 
port_available No String     Used for filtering the results to get the metros where the user has ports. If this parameter is not included the result will contain all the metros where the user has ports or Cloud Exchange is enable

 

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

 

The description of the response payload is as follows:

 

Field name Type Example Description
metros array   An array containing all the available metros to which connections can be made.
name string Amsterdam The name of the metro. 
code string AM The two-character code used to denote the metro.

 

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

 


body: 

GET V2 Seller Services

Note: This API has been deprecated and replaced by GET /ecx/v3/l2/serviceprofiles/services. Refer to GET L2 service profiles services under the API Reference section for more information.

 

GET v2/sellerservices
 Method  GET
 URL or End Point  /ecx/v2/sellerservices
 Headers  Authorization, Content-Type
 Query Parameters  metroCode, pageNumber, pageSize
 Body  Not applicable

 

The services API returns all layer 2 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 layer 2 sellers within SV, USA and a JSON response containing details of a sample seller named John-Doe-Services. 

 

curl -X

GET "https://api.equinix.com/ecx/v2/sellerservices?metro_code=SV"

-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
metro_code No array[string]

SV

 

 The 2 character metro code of the metro for which to retrieve service profiles. If this parameter is not included, the response will contain all the seller services at Equinix.

 

{
  "seller_services": [
    {
      "name": "John-Doe-Services",
      "metros": [
        {
          "availability_status": "In Trail testing",
          "code": "CH",
          "ibxs": [
            "CH2"
          ],
          "name": "Chicago"
        }
      ],
      "allow_custom_speed": "N",
      "standard_speeds": [
        "Up to 50MB",
        "Up to 200MB",
        "Up to 500MB",
        "Up to 1000MB"
      ],
      "require_redundancy": "N",
      "encapsulation": "Dot1q",
      "service_summary": "",
      "service_type": "Layer 2 Cloud Service Connectivity",
      "bgp_community_tag": "",
      "req_buyer_ip_prefixes": "",
      "ipsec_nat_traversal_support": ""
    }
  ]
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
seller_services array[objects]   An array containing the details of the seller service profiles available.
name string John-Doe-Services The name assigned to the service profile.
metros array[objects]   An array containing the metro details associated with this profile where connections can be created.
availability_status string In Trail testing Indicates the availability and reliability of the service profile. In other words, this indicates whether the service offered is in beta, limited availability or GA.
code string CH The metro code denoting metros where connections to this service profile can be created.
ibxs array [string] CH2 An array containing the Equinix IBXs associated with this metro.
name string Chicago The name of the metro.
allow_custom_speed string N Indicates whether or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
standard_speeds array[string] Up to 50MB An array containing the speeds/bandwidth ranges allowed when creating connections to this profile.
require_redundancy string N Specify if your connections require redundancy. If yes, then users need to create a secondary redundant connection.
encapsulation string Dot1q The port encapsulation type for this profile, can be either Dot1q or Qinq.
service_summary string   A summary of the service profile.
service_type string Layer 2 Cloud Service Connectivity The service type supported by this service profile.
bgp_community_tag string   Indicates the BGP tag information for layer 3 connections. It is not applicable to layer 2 connections.
req_buyer_ip_prefixes string   Indicates the IP details for layer 3 connections. It is not applicable to layer 2 connections.
ipsec_nat_traversal_support string   Indicates the Nat details for layer 3 connections.  It is not applicable to layer 2 connections.

 

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

 


body: 

GET V2 Seller Services {profile_name}

Note: This API has been deprecated and replaced by GET /ecx/v3/l2/serviceprofiles/services/{uuid}. Refer to GET L2 service profiles services {uuid} under the API Reference section for more information.

 

GET v2/sellerservices/{profile_name}
 Method  GET
 URL or End Point  /ecx/v2/sellerservices/{profile_name}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

The services API returns the layer 2 service profile details for a given profile name. 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 to obtain the seller details for the profile John-Doe. 

 

curl -X

GET "https://api.equinix.com/ecx/v2/sellerservices/John-Doe"

-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
profile_name Yes string John-Doe

 

 Name of the service profile.
 

 

{
  "seller_services": [
    {
      "name": "John-Doe",
      "metros": [
        {
          "availability_status": "In Trail testing",
          "code": "HK",
          "ibxs": [
            "HK2"
          ],
          "name": "Hong Kong"
        }
        ],
      "allow_custom_speed": "N",
      "standard_speeds": [
        "Up to 1G",
        "Up to 2G",
        "Up to 5G",
        "Up to 10G"
      ],
      "require_redundancy": "N",
      "encapsulation": "Dot1q",
      "service_summary": "You must have AWS Account ID to create Layer 2 connection to Amazon - AWS Direct Connect - High Capacity",
      "service_type": "Layer 2 Cloud Service Connectivity",
      "bgp_community_tag": "",
      "req_buyer_ip_prefixes": "",
      "ipsec_nat_traversal_support": ""
    }
  ]
}

 

The description of the response payload is as follows:

 

Field Name  Type Example Description
seller_services array[object]   An array containing service profile information.
name string John-Doe The name assigned to the service profile.
metros array[object]   An array containing the metro details associated with this profile where connections can be created.
availability_status string

In Trail testing

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

HK

 The metro code denoting metros where connections to this service profile can be created.
ibxs array[string] HK2 Equinix IBX code associated with this metro.
name string

Hong Kong

 Name of the location associated with the IBX and metro.
allow_custom_speed string N Indicates whether or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
standard_speeds array[string] Up to 1G An array containing the speeds/bandwidth ranges allowed when creating connections to this profile.
require_redunancy string N Indicates whether the seller service profile requires a redundant connection to be created.
encapsulation string Dot1q The port encapsulation type for this profile. It can either be Dot1q or Qinq.
service_summary string You must have AWS Account ID to create Layer 2 connection to Amazon - AWS Direct Connect - High Capacity Provides a summary or any additional information about the seller service profile.
service_type string Layer 2 Cloud Service Connectivity Indicates the service type supported by this service profile.
bgp_community_tag string   Indicates the BGP tag information for layer 3 connections. It is not applicable to layer 2 connections
req_buyer_ip_prefixes string   Provides the IP details for layer 3 connections. It is not applicable to layer 2 connections.
ipsec_nat_traversal_support string   Indicates the Nat details for layer 3 connections.  It is not applicable to layer 2 connections.

 

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

 


body: 

POST connection 

Note: This API has been deprecated and replaced by POST /ecx/v3/l2/connections. Refer to the connectivity use cases under How-to Guide section for more information

 

POST /v2/connections
 Method  POST
 URL or End Point  /ecx/v2/connections
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body Parameters  metro_code, service_type, seller_service, primary_name,   primary_port_name, primary_vlan_id, aws_account,   primary_speed

 

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 and Azure 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/v2/connections"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{
  "metro_code": "SV",
  "service_type": "Layer 2 Cloud Service Connectivity",
  "seller_service_name":"AWS Direct Connect - High Capacity",
  "primary_name": "AWS_Demo",
  "primary_port_name": "EQIX-EMERGING-SERVICES-SV4-CX-PRI-03",
  "primary_vlan_id": "450",
  "aws_account": "905272066882",
  "primary_speed":"1 GB"
}'

 

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 '{
  "metro_code": "SV",
  "service_type": "Layer 2 Cloud Service Connectivity",
  "seller_service_name":"AWS Direct Connect",
  "primary_name": "AWS_Demo",
  "primary_port_name": "JOHN-BUYER",
  "primary_vlan_id": "450.451",
  "aws_account": "123456789012",
  "primary_speed":"50 MB"
}'

 

Azure Express route 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 '{

 "metro_code": "SV",
 "service_type": "Layer 2 Cloud Service Connectivity",
 "seller_service_name":"Azure Express Route",
 "redundancy_type":"Dual Home",
 "primary_name": "Azure_Demo_Primary_V2",
 "primary_port_name": "JOHN-BUYER-PRIMARY",
 "secondary_name": "Azure_Demo_Secondary_V2",
 "secondary_port_name": "JOHN-BUYER-SECONDARY",
 "primary_vlan_id": "450",
 "secondary_vlan_id": "451",
 "named_tag": "Public",
 "service_key": "c3c453-6fb0-4b1a-b6ae-83345487",
"primary_speed":"50 MB"

}

 

 

The description of the body parameters is as follows:

 

Body Parameter Name Mandatory Type Example Applicable Values Description
metro_code Yes string SV   The metro in which the connection will be created. 
service_type Yes string Layer 2 Cloud Service Connectivity

Layer 2 Cloud Service Connectivity

Layer 3 Cloud Service Connectivity

 The service type of connection.
seller_service_name Yes string AWS Direct Connect   Name of the provider's service profile.
redundancy_type Yes string  

Single Home

Dual Home 

No Redundancy 

 The type of redundancy associated with connection request.
primary_name Yes string AWS_Demo   Name of the primary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
primary_port_name Yes string JOHN-BUYER-PRIMARY   Name of the buyer's primary port from which the connection would originate.
secondary_name Yes string Azure_Demo_Secondary_V2   Name of the secondary connection.
secondary_port_name Yes string JOHN-BUYER-SECONDARY   Name of the buyer's secondary port from which the connection would originate.
primary_vlan_id Yes string 450.451

 

S-Tag/Outer-Tag and C-Tag/Inner-Tag  of the primary connection.  If the seller service profile requires both outer and inner tag, the value should follow the format: ‘outer-tag.inner-tag’.
secondary_vlan_id Yes string 451

 

 S-Tag/Outer-Tag and C-Tag/Inner-Tag  of the secondary connection.  If the seller service profile requires both outer and inner tag, the value should follow the format: ‘outer-tag.inner-tag’.
named_tag Yes string Public

"Private" 

"Public" 

"Microsoft" 

"Manual"

 The type of peering you would like to set up with Azure Express Route.
aws_account Yes string 123456789012   Authorization Key obtained from the provider. For example, Account ID from AWS.
service_key   string c3c453-6fb0-4b1a-b6ae-83345487   Authorization Key obtained from the provider. Example: Service Key from Azure Express Route.
primary_speed Yes integer 50 MB   Speed/Bandwidth you would like to allocate to the connection.

 

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 an “Access Denied” error, contact your local Equinix Service Desk for Equinix Cloud Exchange Fabric Portal access.

 

{
    "message": "Your Connection request is successful.",
    "result": "SUCCESS",
    "more_info": "",
    "primary_connection_id": "055bbb6b-b36b-4568-b72b-8a225b01fe12",

    "secondary_connection_id": "cc6c4783-5308-421b-b2ac-149e4e204907"
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Your Connection request is successful A descriptive status of the API call.
result string SUCCESS Indicates the status of the API call.
more_info string   Indicates any additional information related to the API call.
primaryConnectionID string 9999a8-0e07-44d0-944c-88a25d8d28f7 Indicates the primary connection ID  of the connection that was created.
secondary_connection_id string cc6c4783-5308-421b-b2ac-149e4e204907 Indicates the secondary connection ID  of the connection that was created.

 

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

 


body: 

PATCH connection {connection_id}

Note: This API has been deprecated and replaced by PATCH /ecx/v3/l2/connections/{connId}. Refer to step 3 under Connect to AWS section for more information.

 

PATCH v2/hostedconnection/connection/{connection_id}
 Method  PATCH
 URL or End Point  /ecx/v2/hostedconnection/connection/{connection_id}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body Parameters  Connection type, AWS Access Keys (Access ID and Secret Key)

 

Connection_id is an identifier unique for each connection.

 

The PATCH connections API is used for accepting a given 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 accept a layer 2 connection and its respective JSON response. 

 

curl -X

PATCH "https://api.equinix.com/ecx/v2/hostedconnection/connection/9999a8-0e07-44d0-944c-88a25d8d28f7"

-H "content-type: application/json"

-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

-d '{

"connection_type":"single",

"access_id":"AKIAGGJKJU7BC3QJKYQ",

"secret_key":"CXGJW1lWbqENEqSkBAK"

}'

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

Field Name Type Example Description
message string Connection enabling request successful  A descriptive status of the API call.
result string SUCCESS Indicates the status of the PATCH API call.
more_info string   Indicates any additional information related to the API call.

 

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

 


body: 

GET Connections

Note: This API has been deprecated and replaced by GET /ecx/v3/l2/buyer/connections. Refer to GET L2 buyer connections under the API Reference section for more information.

 

GET v2/connections
 Method  GET
 URL or End Point  /ecx/v2/connections
 Headers  Authorization, Content-Type
 Query Parameters  metro_code, seller_port_name, state, pending, metadata, search_type
 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/v2/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
metro_code No string DC

 

 The 2 character code denoting the metro to which connections have been created. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv). 
seller_port_name No string JohnDoePort   The name of the seller port.
state No string PROVISIONED

"PROVISIONED"

"DEPROVISIONED"

"PENDING_APPROVAL"

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

"add"

"delete"

Status of the connections. This is a mandatory parameter for Seller. Possible values are

add - To get all the connections that are created by a buyer but not yet accepted by the seller
delete - To get all the connections that are deleted by a buyer but not yet accepted the deletion by the seller
metadata No string     Metadata.
search_type No string AND

"AND"

"OR"

 Filter criteria for metadata.

 

{
  "connections": [
    {
      "id": "3a4ca7d6-3f03-4928-85cd-44f442eae046",
      "name": "John_Demo_Connection",
      "connection_type": "Layer 2 Cloud Service Connectivity",
      "buyer_port_name": "JD-SV4-PRI-03",
      "seller_service_name": "AWS Direct Connect - High Capacity",
      "service_key": "1234566882",
      "aws_account": "1234566882",
      "digital_authorization_key": "1234566882",
      "buyer_vlan_id": "790",
      "speed": "Up to 1G",
      "state": "Provisioned",
      "status": "Enabled",
      "created_date": "02/20/2020 03:43:10",
      "created_by": "John Doe",
      "notification_contacts": [
        "johnDoe@equinix.com"
      ],
      "seller_port_name": "jd-fg2l33c",
      "seller_vlan_id": "710",
      "metro_code": "SV",
      "metro_name": "Silicon Valley",
      "ibx_name": "SV1",
      "redundant_id": "",
      "instance_id": "",
      "instance_speed": "",
      "billing_tier": "Up to 1G",
      "equinix_bgp_asn": "",
      "equinix_peer_ip": "",
      "buyer_bgp_asn": "",
      "buyer_peer_ip": "",
      "bgp_authentication_key": "",
      "named_tag": null,
      "purchase_order_no": "1234",
      "buyer_public_prefixes": "",
      "metadata": []
    }
  ]
}

 

The description of the response payload is as follows:

 

Field Type Example Description
connections array    
id string 3a4ca7d6-3f03-4928-85cd-44f442eae046 The unique identifier of the connection.
name string John_Demo_Connection Name of the connection.
connection_type string Layer 2 Cloud Service Connectivity Indicates the type of connection.
buyer_port_name string JD-SV4-PRI-03 The name of the port from which the connection is established. (i.e. A-side port name)
seller_service_name string AWS Direct Connect - High Capacity The name of the seller profile associated with the connection.
service_key string 1234566882 The AWS key used by the user/customer for this connection.
aws_account string 1234566882 The AWS account used by the user/customer for this connection.
digital_authorization_key string 1234566882 The authorization key used by the user/customer when creating connections to seller profiles.
buyer_vlan_id string 450 The Stag of the connection.
speed string Up to 1G Bandwidth speed
state string Provisioned The status of the connection at Equinix's end.
status string Enabled  
created_date string 02/20/2020 03:00:40 The date on which the connection was created.
created_by string John Doe The username of the user who created the connection.
notification_contacts string null The email address of the contact to be notified during any updates on the connection.
seller_port_name string jd-fg2l33c Z-side port name.
seller_vlan_id string 710 The S Tag of the Z side port.
metro_code string SV The metro code denoting the source metro from where the connection was created. 
metro_name string

Silicon Valley

 The name of the source metro from where the connection was created. 
ibx_name string SV4 Name of the Equinix IBX associated with this metro.
redundant_id string   The unique ID that groups a primary and secondary connection.
instance_id string

 

 Provides the instance ID. It is not applicable to layer 2 connections.
instance_speed string   Indicates the instance speed. It is not applicable to layer 2 connections.
billing_tier string Up to 1G Billing tier for connection.
equinix_bgp_asn string

 

 Indicates the Equinix BGP ASN information for layer 3 connections. It is not applicable to layer 2 connections.
equinix_peer_ip string  

 

 Provides the peering details for layer 3 connections. It is not applicable to layer 2 connections.
buyer_bgp_asn string

 

 Indicates the Buyer BGP ASN information for layer 3 connections. It is not applicable to layer 2 connections.
buyer_peer_ip string   Provides the peering IP details for layer 3 connections. It is not applicable to layer 2 connections.
bgp_authentication_key string   Indicates the BPG authentication details for layer 3 connections. It is not applicable to layer 2 connections.
named_tag string   The type of peering for Azure Express Route.
purchase_order_no string 1234 An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
buyer_public_prefixes string   Indicates the IP details for layer 3 connections. It is not applicable to layer 2 connections.
metadata array[string]   An array of data providing information about other data.

 

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

 


body: 

GET Connections {connection_id}

Note: This API has been deprecated and replaced by GET /ecx/v3/l2/connections/{uuid}. Refer to GET L2 connections {uuid} under the API Reference section for more information.

 

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

 

The connections API returns connection details for a given layer 2 connection ID. 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.

 

Connection ID 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/v2/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.
 

 

{
  "connections": [
    {
      "id": "c58484c1-e274-4b3a-b8ad-c7c9415e2d42",
      "name": "John_Demo_Connection",
      "connection_type": "Layer 2 Cloud Service Connectivity",
      "buyer_port_name": "JD-SV4-PRI-03",
      "seller_service_name": "AWS Direct Connect - High Capacity",
      "service_key": "1234566882",
      "aws_account": "1234566882",
      "digital_authorization_key": "1234566882",
      "buyer_vlan_id": "450",
      "speed": "Up to 1G",
      "state": "Provisioned",
      "status": "Enabled",
      "created_date": "02/20/2020 03:00:40",
      "created_by": "John Doe",
      "notification_contacts": null,
      "seller_port_name": "jd-fg2l33c",
      "seller_vlan_id": "710",
      "metro_code": "SV",
      "metro_name": "Silicon Valley",
      "ibx_name": "SV4",
      "redundant_id": "",
      "instance_id": "",
      "instance_speed": "",
      "billing_tier": "Up to 1G",
      "equinix_bgp_asn": "",
      "equinix_peer_ip": "",
      "buyer_bgp_asn": "",
      "buyer_peer_ip": "",
      "bgp_authentication_key": "",
      "named_tag": null,
      "purchase_order_no": "",
      "buyer_public_prefixes": "",
      "metadata": []
    }
  ]
}

 

The description of the response payload is as follows:

 

Field Type Example Description
connections array    
id string c58484c1-e274-4b3a-b8ad-c7c9415e2d42 The unique identifier of the connection.
name string John_Demo_Connection Name of the connection.
connection_type string Layer 2 Cloud Service Connectivity Indicates the type of connection.
buyer_port_name string JD-SV4-PRI-03 The name of the port from which the connection is established. (i.e. A-side port name)
seller_service_name string AWS Direct Connect - High Capacity The name of the seller profile associated with the connection.
service_key string 1234566882 The AWS key used by the user/customer for this connection.
aws_account string 1234566882 The AWS account used by the user/customer for this connection.
digital_authorization_key string 1234566882 The authorization key used by the user/customer when creating connections to seller profiles.
buyer_vlan_id string 450 The Stag of the connection.
speed string Up to 1G Bandwidth speed
state string Provisioned The status of the connection at Equinix's end.
status string Enabled  
created_date string 02/20/2020 03:00:40 The date on which the connection was created.
created_by string John Doe The username of the user who created the connection.
notification_contacts string null The email address of the contact to be notified during any updates on the connection.
seller_port_name string jd-fg2l33c Z-side port name.
seller_vlan_id string 710 The S Tag of the Z side port.
metro_code string SV The metro code denoting the source metro from where the connection was created. 
metro_name string

Silicon Valley

 The name of the source metro from where the connection was created. 
ibx_name string SV4 Name of the Equinix IBX associated with this metro.
redundant_id string   The unique ID that groups a primary and secondary connection.
instance_id string

 

 Provides the instance ID for layer 3 connections. It is not applicable to layer 2 connections.
instance_speed string   The instance speed for layer 3 connections. It is not applicable to layer 2 connections.
billing_tier string Up to 1G Billing tier for connection.
equinix_bgp_asn string

 

 Indicates the Equinix BGP ASN information for layer 3 connections. It is not applicable to layer 2 connections
equinix_peer_ip string

 

 Provides the peering details for layer 3 connections. It is not applicable to layer 2 connections.
buyer_bgp_asn string

 

 Indicates the Buyer BGP ASN information for layer 3 connections. It is not applicable to layer 2 connections.
buyer_peer_ip string   Provides the peering IP details for layer 3 connections. It is not applicable to layer 2 connections.
bgp_authentication_key string   Indicates the BPG authentication details for layer 3 connections. It is not applicable to layer 2 connections
named_tag string   The type of peering for Azure Express Route.
purchase_order_no string   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
buyer_public_prefixes string   Indicates the IP details for layer 3 connections. It is not applicable to layer 2 connections.
metadata array[string]   An array of data providing information about other data.

 

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

 


body: 

DELETE Connections {connection_id}

Note: This API has been deprecated and replaced by DELETE /ecx/v3/l2/connections/{uuid}. Refer to DELETE L2 connections {uuid} under the API Reference section for more information.

 

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

 /ecx/v2/connections/{connection_id}
 Headers  Authorization, Content-Type
 Query Parameters  Not applicable
 Body  Not applicable

 

This API deletes the connection of a given connection ID. 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.

 

Connection_id is an identifier unique for each connection.

 

If the connection is connected to a seller service provider other than Azure or AWS, the respective seller service provider must acknowledge this delete request for the connection to be deleted.

 

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 connection_id 702d31c4-c66d-49b0-a26c-a9a234e56fsb 

 

curl -X

DELETE "https://api.equinix.com/ecx/v2/connections/702d31c4-c66d-49b0-a26c-a9a234e56fsb"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

{
    "message": "Your connection has been deleted successfully.",
    "result": "SUCCESS",
    "more_info": null
}

 

The description of the response payload is as follows:

 

Field Name Type Example values Description
message string Your connection has been deleted successfully. A descriptive status of the API call.
result string SUCCESS Indicates the status of the API call.
 
more_info string null Indicates any additional information related to the API call.

 

 

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/v2/connections/{connection_id}

 


body: 

Layer 2 Buyer APIs (V3)


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 returns the 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 all designated ports, and its respective JSON response containing the 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
    }
]

 

Pay attention to the metroCode attribute received in the response, as this indicates where the connection would be established from. This can be cross-referenced with the response from /ecx/v3/l2/metros API to discover all the 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

Indicates whether the port supports unlimited connections.

If  "false", the port is a standard port with limited connections.

If  "true", the port is an "unlimited connections" port that allows multiple connections at no additional charge. 
custOrgId string 99966 The organization ID of the customer who owns the port.
ibx string SV1 The Equinix IBX where the port resides.
metroCode string

SV

 The metro code of the metro where the port resides.
metroDescription string Silicon Valley The name of the metro 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) where the port resides.
encapsulation string

Dot1q

QinQ

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

true

false

 If "false", outgoing connections from the port cannot be viewed.
placeVcOrderPermission boolean

true

false

 If  "true", the user can create, modify or delete connections from this port. 
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 The port bandwidth in bytes.
crossConnectId string 20883104 The cross-connect ID associated with the member port.
layer3Enabled boolean

true

false

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

true

false

 Indicates whether 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: 

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 Connection Price

GET l2/connections/prices
 Method  GET
 URL or End Point  /ecx/v3/l2/connections/prices
 Headers  Authorization, Content-Type
 Query Parameters  customSpeeds, destinationMetro, portUUID
 Body  Not applicable

 

The prices API returns the estimated price of connection between a given port ID and metro. You can use the GET userport and GET metros API to retrieve your port and metro details. 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.

 

This API only provides an estimated price. Additional taxes and/or fees may apply depending on the metro you have selected.

 

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 its respective JSON response to get the price of a layer 2 connection from a given port to SV. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/connections/prices?customSpeeds=50,100&destinationMetro=SV&portUUID=91469d07-dd6f-d6f2-1de0-37c8bc10af30"

-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
customSpeeds No array[string] 50

50

200

500

1000

2000

5000

10000

 Speed/Bandwidth you intend to allocate to the connection.
destinationMetro Yes string

SV

 

 The two-character code denoting the metro where you would like to connect.
portUUID Yes string 91469d07-dd6f-d6f2-1de0-37c8bc10af30   Unique identifier of the port from which the connection would originate.

 

{
    "currency": "CHF",
    "originMetro": "GV",
    "destinationMetro": "SV",
    "priceList": [
        {
            "productName": "ECX Fabric Service Provider Product",
            "connectionType": "localConnection",
            "prices": [
                {
                    "speedBillingTier": "50",
                    "price": "0"
                },
                {
                    "speedBillingTier": "200",
                    "price": "0"
                },
                {
                    "speedBillingTier": "500",
                    "price": "0"
                },
                {
                    "speedBillingTier": "1000",
                    "price": "0"
                },
                {
                    "speedBillingTier": "2000",
                    "price": "0"
                },
                {
                    "speedBillingTier": "5000",
                    "price": "0"
                },
                {
                    "speedBillingTier": "10000",
                    "price": "0"
                }
            ]
        },
        {
            "productName": "ECX Fabric Remote Connection Product",
            "connectionType": "remoteConnection",
            "prices": [
                {
                    "speedBillingTier": "50",
                    "price": "230.0"
                },
                {
                    "speedBillingTier": "200",
                    "price": "400.0"
                },
                {
                    "speedBillingTier": "500",
                    "price": "580.0"
                },
                {
                    "speedBillingTier": "1000",
                    "price": "1280.0"
                },
                {
                    "speedBillingTier": "2000",
                    "price": "2150.0"
                },
                {
                    "speedBillingTier": "5000",
                    "price": "4945.0"
                },
                {
                    "speedBillingTier": "10000",
                    "price": "8380.0"
                }
            ]
        }
    ]
}

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
currency string

CHF

 The currency in which the prices are shown. The currency indicated depends on where your port resides. 
originMetro string GV The two-character code denoting the metro where the port resides and where the connection is established from.
destinationMetro string

SV

 The two-character code denoting the metro where you would like to connect.
productName string ECX Fabric Service Provider Product The name of the product.
connectionType string

localConnection

remoteConnection

Indicates whether the pricing listed under is for a local connection or remote connection.

 

Local connections have a fixed charge depending on the speed you have selected, whereas remote connection prices comprise a local connection charge and remote surcharge.
prices array[object]   An object containing the price details.
speedBillingTier string 50 The speed of the connection in MB.
price string 0 The price of the connection.

 

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 layer 2 seller service profiles available for the user to 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 to obtain details of layer 2 seller profiles within DC, USA and a JSON response containing details of a sample seller profile 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 two-character code denoting 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 a response for this 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.
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 The label which the user will see when creating connections.
requiredRedundancy boolean

true

false

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

 

If requireRedundancy is true, the user will either need two different ports (primary port and secondary port) for each connection or one port with two connections (primary and secondary).
allowCustomSpeed boolean

true

false

 Indicates whether the profile allows custom speed/bandwidth when creating connections to this profile.
speedBands array   An array containing the speed/bandwidth supported by this profile.
speed double

50

200

500

1000

 The speed/bandwidth supported by this profile.
unit string MB Unit of the speed/bandwidth supported by this profile.
metros array   The metros associated with this profile.
code string SV The metro code denoting the metro where this service profile is available for creating connections.
name string Silicon Valley The name of the metro where this service profile is available for creating connections.
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 on which the service profile was created.
createdBy string John-Doe The username of the user who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The date on which the service profile was last updated.
lastUpdatedBy string John-Doe The username of the user who last updated the service profile.
vlanSameAsPrimary boolean

true

false

 Indicates whether the same VLAN can be used for both primary and secondary connections.
tagType string

CTAGED

BOTH

NAMED

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

true

false

 Indicates whether the service profile has been integrated via APIs with Equinix for automated provisioning of connections.
selfProfile boolean

true

false

 Indicates whether the profile is an internal profile used for creating connections within the seller organization.
speedfromAPI boolean

true

false

 Indicates whether the bandwidth of the connection can be obtained directly from the cloud service provider.
profileEncapsulation string

Dot1q

Qinq

 The type of port encapsulation supported by this profile. Applicable values are Dot1q and QinQ.
authorizationKey string [a-z|A-z|0-9] Authorization Key obtained from the provider to create connections to this profile. e.g. - Account ID for AWS, Service key for Azure, etc
organizationName string John-Doe-Corp The name of the seller service organization associated with this service profile.
private boolean

true

false

Indicates whether this is a private profile. Unlike public profiles such as AWS/Azure/Oracle/Google, etc, users can only create connections to private profiles after the seller has granted permissions.
features object   An object containing feature-related information such as cloudReach, testProfile, etc.  
cloudReach boolean

true

false

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

true

false

 Indicates whether 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 details of a given layer 2 service 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

 

 The unique identifier of the 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 The label which the user will see when creating connections.
requiredRedundancy boolean

true

false

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

 

If requireRedundancy is true, the user will either need two different ports (primary port and secondary port) for each connection or one port with two connections (primary and secondary).
allowCustomSpeed boolean

true

false

 Indicates whether the profile allows custom speed/bandwidth when creating connections to this profile.
speedBands string   An array containing the speed/bandwidth supported by this profile.
speed double

50

200

500

1000

 The speed/bandwidth supported by this profile.
unit string MB Unit of the speed/bandwidth supported by this profile.
metros array   The metros associated with this profile.
code string SV The metro code denoting the metro where this service profile is available for creating connections.
name string Silicon Valley The name of the metro where this service profile is available for creating connections
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 on which the service profile was created.
createdBy string John-Doe The username of the user who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The date on which the service profile was last updated.
lastUpdatedBy string John-Doe The username of the user who last updated the service profile.
vlamSameAsPrimary boolean

true

false

 Indicates whether the same VLAN can be used for both primary and secondary connections.
tagType string

CTAGED

BOTH

NAMED

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

true

false

 Indicates whether the service profile has been integrated via APIs with Equinix for automated provisioning of connections.
selfProfile boolean

true

false

 Indicates whether the profile is an internal profile used for creating connections within the seller organization.
speedfromAPI string

true

false

 Indicates whether the bandwidth of the connection can be obtained directly from the cloud service provider.
profileEncapsulation string

Dot1q  

Qinq

 The type of port encapsulation supported by this profile. Applicable values are Dot1q and QinQ.
authorizationKey string [a-z|A-z|0-9] Authorization Key obtained from the provider to create connections to this profile. e.g. - Account ID for AWS, Service key for Azure, etc
organizationName string John-Doe-Corp The name of the seller service organization associated with this service profile.
private boolean

true

false

 Indicates whether this is a private profile. Unlike public profiles such as AWS/Azure/Oracle/Google, etc, users can only create connections to private profiles after the seller has granted permissions.
features object   An object containing feature-related information such as cloudReach, testProfile, etc.
cloudReach boolean

true

false

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

true

false

 Indicates whether 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 the authorization key (AWS account ID/ Microsoft service key/ Google pairing key etc). to connect to cloud service providers. 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 account ID for AWS, service key for Azure, pairing key for Google, cloud ID for Oracle.
metroCode Yes string DC

 

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

"AMER"

"EMEA"

"APAC"

 The region where 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/speed of the primary connection.
secondary object   An object containing secondary connection information.
bandwidth string 50MB The bandwidth/speed 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, authorizationKey, buyerPortName, buyerPortUUID, searchtType, subAccount, pageNumber, pageSize
 Body  Not applicable

 

The connections 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 and its JSON response to obtain all outgoing layer 2 connections for the user credentials submitted. 

 

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 is 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 code denoting the metro to which connections have been created. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv). 
authorizationKey No string     Connection credentials required to create a layer 2 connection. For example, account ID for AWS, service key for Azure, pairing key for Google, cloud ID for Oracle. 
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   This parameter is only applicable to 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.
content object   An array containing the response data.
asideEncapsulation string

"Dot1q"

"Qinq"

 The encapsulation of the buyer port (Applicable values are Dot1q or QinQ).
authorizationKey string 99973578-36f9-47f8-b12f-afa3faf02d06 Authorization Key obtained from the provider to create 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 of the user 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 of the user 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 last updated the connection.
namedTag string Private The type of peering to set up with Azure Express Route.
notification array[string]   The email address of the contact who would be notified when there are any updates on this connection.
metroCode string TR The metro code denoting the source metro where this connection was created from. 
metroDescription string   The name of the metro where this connection was created from. 
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 this connection is connected to a private profile.
purchaseOrderNumber string   An optional field to link the purchase order numbers to the connection on Equinix which would be reflected on the invoice.
redundancyGroup string 28c02121-f093-4340-90c9-081b17b239c8 A unique ID that groups the primary and secondary connection.
redundancyType string secondary The type of connection. It can either be primary or secondary.
remote boolean

true

false

 Indicates whether the connection is a remote connection.  (If the seller and buyer metros of the connection are different then it is a remote connection.)
self boolean

true

false

 Indicates whether the connection is a self-connection. (i.e. the source (A-side) and destination (Z-side) belongs to the same organization.) 
sellerMetroCode string TR The metro code that denotes the connection’s destination (Z side).
sellerMetroDescription string Toronto The destination (Z side) metro of the connection. 
sellerOrganizationName string John Doe Org The name of the seller service organization associated with this connection.
sellerServiceName string Azure Express Route The name of the seller service profile associated with this connection.
sellerServiceUUID string a1390b22-bbe0-4e93-ad37-85beef9d254d The ID of the seller service profile associated with this connection.
speed integer 50 Speed/Bandwidth be allocated to the connection.
speedUnit string MB Unit of the speed/bandwidth allocated to the connection.
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 this 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: 

Get Port Stats {uuid}

GET /stats/port/{uuid}
 Method  GET
 URL or End Point  /ecx/v3/stats/port/{uuid}
 Headers  Authorization, Content-Type
 Query Parameters  startDate, endDate
 Body  Not applicable

 

The port stats API retrieves the inbound and outbound traffic utilization statistics of a given port for a specified time. 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 its JSON response to obtain the usage stats of a port between July 24th, 2019 and August 24th, 2019. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/stats/port/67344add-9351-3510-b4e0-30ac094f8af1?startDate=2019-07-24T05:12:44Z&endDate=2019-08-24T05:12:44Z"

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the request payload is as follows:

 

URL Parameter Name Mandatory Type Example Applicable Values Description
UUID Yes string 67344add-9351-3510-b4e0-30ac094f8af1   The unique identifier of the port.

 

Query Parameter Name Mandatory Type Example Applicable Values Description
startDate Yes Date 2019-07-24T05:12:44Z   Start date in UTC.
endDate Yes Date 2019-08-24T05:12:44Z   End date in UTC.

 

{
    "capacity": 1000000000,
    "inboundMax": 0.002355751111111111,
    "inboundAvg": 0.0010500154503046038,
    "outboundMax": 0.0006338511111111111,
    "outboundAvg": 0.0003315938400648824,
    "inboundLastPolled": 0.0011289177777777776,
    "outboundLastPolled": 0.00030397999999999997,
    "inboundStats": [
        {
            "time": "2019-07-24T05:00:00Z",
            "max": 0.0009884177777777778,
            "mean": 0.0009884177777777778
        },
        {
            "time": "2019-07-24T09:00:00Z",
            "max": 0.0009884177777777778,
            "mean": 0.0009884177777777778
        }],

  "outboundStats": [
        {
            "time": "2019-10-16T14:00:00Z",
            "max": 0.00014062666666666665,
            "mean": 0.00014062666666666665
        },
        {
            "time": "2019-10-16T15:00:00Z",
            "max": 0.0003326533333333333,
            "mean": 0.0003326533333333333
        }

}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
capacity integer 1000000000 Port Bandwidth in bits.
inboundMax integer 0.002355751111111111 Maximum inbound traffic for the given time frame. 
inboundAvg integer

0.0010500154503046038

Average inbound traffic for the given time frame.
outboundMax integer

0.0006338511111111111

 Maximum outbound traffic for the given time frame.
outboundAvg integer 0.0003315938400648824 Average outbound traffic for the given time frame.
inboundLastPolled integer 0.0011289177777777776 Last recorded inbound traffic. 
outboundLastPolled integer 0.00030397999999999997 Last recorded outbound traffic.
inboundStats array

 

An array containing inbound usage statistics. The data is displayed based on the start and end date query parameters.

If the start and end time period is between 1 and 7 days, the stats are displayed in 5-minute intervals.

If the time period is between 7 days and 90 days, the stats are displayed in 1-hour intervals.
time string 2019-07-24T05:00:00Z

The time at which the data was recorded. The time format is UTC.
max integer 0.0009884177777777778 The maximum traffic for a given interval.
mean integer

0.0009884177777777778

 The average traffic for a given interval.
outboundStats array   An array containing inbound usage statistics.

 

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

 


body: 

DELETE L2 Connections {uuid}

DELETE l2/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 a given layer 2 connection. 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 its JSON response to delete a connection with UUID 702d31c4-c66d-49b0-a26c-a9a234e56fsb. 

 

curl -X

DELETE "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 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: 

Layer 2 Seller APIs (V3)


body: 

Delete L2 Service Profiles {uuid}

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

 

This API deletes the service profile of a given layer 2 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.

 

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 screenshot shows a sample curl request to delete an L2 seller profile. 

 

curl -X

DELETE "https://api.equinix.com/ecx/v3/l2/serviceprofiles/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 the service profile.
 

 

{
   "message": "UUID's [c9d90584-30f4-4fc0-90be-d63c4430fa24] successfully deleted",
   "status": "SUCCESS"
}

 

The description of the response payload is as follows:

 

Field Name  Type Example Description
message string UUID successfully deleted Description of the status.
status string SUCCESS The status of the API call.

 

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

 


body: 

GET L2 Seller Connections

GET l2/seller/connections
 Method  GET
 URL or End Point  /ecx/v3/l2/seller/connections
 Headers  Authorization, Content-Type
 Query Parameters  status, metroCode, portName, state, profileId, pageNumber, pageSize
 Body  Not applicable

 

This API returns the details of all the connections connected to the service profiles affiliated to the submitted user credentials. 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 to obtain all incoming layer 2 connections associated with the user credentials submitted. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/seller/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"

"PENDING_APPROVAL"

"PROVISIONING"

"ORDERING"

"REJECTED"

"APPROVED"

"PENDING_DEPROVISIONING"

"PENDING_DELETE"

"DELETED"

"NOT_PROVISIONED"

"MIGRATION_STARTED" "MIGRATION_DEPROVISIONED" "MIGRATION_DEPROVISION_FAILED" "MIGRATION_VLAN_RELEASED"

"MIGRATION_VLAN_RELEASE_FAILED"

"MIGRATION_VLAN_GENERATED" "MIGRATION_VLAN_GENERATION_FAILED" "MIGRATION_PROVISION_FAILED"

 The status of the connection at Equinix's end (Z-Side).
metroCode No string DC

 

 The 2 character code denoting the metro to which connections have been created. It can be a single code (&metroCode=Dc) or an array of codes (&metroCode=Dc&metroCode=Sv).
portName No string JohnDoePort   The name of the seller port.
state No string 006d08e2-788e-4c83-82d3-07b1787644a5   The state of the connection.
profileId No string JohnDoe2Port   The unique identifier of the seller service profile.
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",

            "zsideEncapsulation": "dot1q",
            "metroCode": "DC",
            "metroDescription": "Ashburn",
            "providerStatus": "DEPROVISIONED",
            "status": "DEPROVISIONED",
            "billingTier": "Up to 50 MB",
            "speed": 50,
            "speedUnit": "MB",
            "redundancyType": "secondary",

            "redundancyGroup": "8a8a10d9-956f-46ad-a510-ebeaf810fcdf",
            "sellerMetroCode": "TR",
            "sellerMetroDescription": "Toronto",
            "sellerServiceName": "Azure Express Route",

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

            "createdDate": "2018-08-30T04:20:36.033Z",
            "createdBy": "JohnDoe@equinix.com",
            "createdByFullName": "JohnDoe",
            "createdByEmail": "JohnDoe@equinix.com",

            "lastUpdatedBy": "JohnDoe",
            "lastUpdatedDate": "2018-09-14T02:21:06.425Z",

            "lastUpdatedByFullName": "JohnDoe",
            "lastUpdatedByEmail": "JohnDoe@equinix.com",
            "deletedBy": "JohnDoe@equinix.com",
            "deletedDate": "2018-09-02T16:03:36.349Z",
            "deletedByEmail": "JohnDoe@equinix.com",

            "updateInProgress": false,
            "zSidePortName": "John-Port",
            "zSidePortUUID": "6f5680ea-1513-5130-50e0-30ac094f83ec",
            "zSideVlanSTag": 8,
            "remote": false,
            "private": false,
            "self": false

            "redundantUUID": "79f53f74-31c9-4e77-a7f2-5fdb181a7e07"

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

Field Type Example Values Description
isFirstPage boolean

true

false

 Indicates whether the page being displayed is the first page.
totalCount integer 467 The number of items returned as a response for this API request.
isLastPage boolean

true

false

 Indicates whether the page being displayed is the last page.
pageSize integer 20 The number of items to be displayed per page. 
content array[object]   An array containing the response data.
buyerOrganizationName string JOHN-DOE-ORG The name of the buyer organization associated with this connection
uuid string 006d08e2-788e-4c83-82d3-07b1787644a5 The unique identifier of the connection.
asideEncapsulation string

"Dot1q"

"Qinq"

 The encapsulation of the buyer port. (Applicable values are Dot1q or QinQ).
billingTier string Up to 50 MB Billing tier for connection.
createdBy string JohnDoe@equinix.com The username of the user 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 JohnDoe The username of the user who updated the connection.
lastUpdatedDate string 2018-09-14T02:21:06.425Z The date on which the connection was last updated.
lastUpdatedByEmail string JohnDoe@equinix.com The email ID of the user who updated the connection.
lastUpdatedByFullName string JohnDoe The full name of the user who updated the connection.
deletedBy string JohnDoe@equinix.com The username of the user who deleted the connection.
deletedDate string 2018-09-02T16:03:36.349Z The date on which the connection was deleted.
deletedByEmail string JohnDoe@equinix.com The email ID of the user who deleted the connection.
updateInProgress boolean false  
notifications array[string] JohnDoe@equinix.com A list of email addresses that would be notified when there are any updates on this connection.
metroCode string DC The metro code denoting the source metro from where the connection was created. 
metroDescription string Ashburn The name of the metro from where the connection was 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 this connection is connected to a private profile.
purchaseOrderNumber string   An optional field to link the purchase order numbers to the connection on Equinix which would be reflected on the invoice.
redundancyGroup string 28c02121-f093-4340-90c9-081b17b239c8 A unique ID that groups the primary and secondary connection.
redundancyType string secondary The type of connection. It can either be primary or secondary.
remote boolean

true

false

 Indicates whether the connection is a remote connection.  (If the seller and buyer metros of the connection are different then it is a remote connection.)
self boolean

true

false

 Indicates whether the connection is a self-connection. (i.e. the source (A-side) and destination (Z-side) belongs to the same organization.) 
sellerMetroCode string Tr The metro code that denotes the connection’s destination (Z side).
sellerMetroDescription string Toronto The destination (Z side) metro of the connection. 
sellerOrganizationName string John Doe Org The name of the seller service organization associated with this connection
sellerServiceName string Azure Express Route The name of the seller service profile associated with this connection.
sellerServiceUUID string a1390b22-bbe0-4e93-ad37-85beef9d254d The ID of the seller service profile associated with this connection.
speed integer 50 Speed/Bandwidth be allocated to the connection.
speedUnit string MB Unit of the speed/bandwidth allocated to the connection.
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.
       
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.
redundantUUID integer 79f53f74-31c9-4e77-a7f2-5fdb181a7e07 The UUID of a primary connection or secondary connection.

 

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

 


body: 

Get L2 Service Profiles

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

 

The serviceprofiles API returns all layer 2 service profiles affiliated to 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 details of layer 2 seller profiles 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?pageSize=150&state=APPROVED"

-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 150   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. 
state No array[string]

APPROVED

"PENDING_APPROVAL"
"APPROVED"
"REJECTED"
"DELETED"

 The state of the profiles requested.

 

{
    "isLastPage": true,
    "isFirstPage": true,
    "totalCount": 147,
    "pageSize": 150,
    "content": [
        {
            "uuid": "9da3f720-6982-4c40-aa80-af3aad5852a1",
            "name": "JohnDoe_TEST_Profile",
            "requiredRedundancy": false,
            "connectionNameLabel": "Connection",
            "equinixManagedPortAndVlan": false,
            "apiAvailable": false,
            "allowOverSubscription": false,
            "vlanSameAsPrimary": false,
            "tagType": "CTAGED",
            "enableAutoGenerateServiceKey": false,
            "onProfileApprovalRejectNotification": [
                "JohnDoe@equinix.com"
            ],
            "onBandwidthThresholdNotification": [
                "JohnDoe@equinix.com"
            ],
            "onVcApprovalRejectionNotification": [
                "JohnDoe@equinix.com"
            ],
            "ports": [
                {
                    "id": "8e638dbf-1713-7130-64e0-30ac094f85f6",
                    "sellerRegion": null,
                    "sellerRegionDescription": null,
                    "metroCode": "SV",
                    "inTrail": null,
                    "crossConnectId": null,
                    "xa": null
                }
            ],
            "allowCustomSpeed": false,
            "speedFromAPI": false,
            "speedBands": [
                {
                    "speed": 50,
                    "unit": "MB"
                },
                {
                    "speed": 200,
                    "unit": "MB"
                },
                {
                    "speed": 500,
                    "unit": "MB"
                },
                {
                    "speed": 1000,
                    "unit": "MB"
                }
            ],
            "description": "JohnDOe Testing",
            "state": "APPROVED",
            "createdDate": "2019-08-15T10:19:46.092Z",
            "createdBy": "JohnDoe",
            "lastUpdatedDate": "2019-09-12T02:07:11.156Z",
            "lastUpdatedBy": "JohnDoe",
            "createdByFullName": "John Doe",
            "lastUpdatedByFullName": "John Doe",
            "createdByEmail": "JohnDoe@equinix.com",
            "updatedByEmail": "JohnDoe@equinix.com",
            "organizationName": "John-Doe-Corp",
            "allowHighAvailability": true,
            "allowAuthorizationKeyReUse": true,
            "allowSecondaryLocation": true,
            "private": true,
            "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.
isFirstPage boolean

true

false

 Indicates whether the page being displayed is the first page.
totalCount integer 23 The number of items returned as a response for this API request.
pageSize integer 20 The number of items to be displayed 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.
requiredRedundancy boolean

true

false

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

 

If requireRedundancy is true, the user will either need two different ports (primary port and secondary port) for each connection or one port with two connections (primary and secondary).
connectionNameLabel string JohnDoeConnection The label which the user will see when creating connections.
equinixManagedPortAndVlan boolean

true

false

 Indicates whether the VLAN ID details are managed by Equinix.
apiAvailable boolean

true

false

 Indicates whether the service profile has been integrated via APIs with Equinix for automated provisioning of connections.
allowOverSubscription      
vlanSameAsPrimary boolean

true

false

 Indicates whether the same VLAN can be used for both primary and secondary connections.
tagType string

CTAGED

BOTH

NAMED

 The type of tagging to be used when connecting to this service profile. The default value is CTAGED.
enableAutoGenerateServiceKey      
onProfileApprovalRejectNotification string JohnDoe@equinix.com The email id to be notified when the profile gets approved or rejected.
onBandwidthThresholdNotification string JohnDoe@equinix.com The email id to be notified when the port bandwidth exceeds. 
onVcApprovalRejectionNotification string JohnDoe@equinix.com The email id to be notified if an incoming connection is approved or rejected.
ports array   An array containing port information.
id string 8e638dbf-1713-7130-64e0-30ac094f85f6 The ID of the port.
sellerRegion string   The region in which the seller port resides.
sellerRegionDescription string   The description of the seller region.
metroCode string SV The metro code of the port associated with this profile.
inTrail string    
crossconnectId string    
xa string    
allowCustomSpeed boolean

true

false

 Indicates whether the profile allows custom speed/bandwidth when creating connections to this profile.
speedfromAPI string

true

false

 Indicates whether the bandwidth of the connection can be obtained directly from the cloud service provider.
speedBands array   An array containing the speed/bandwidth supported by this profile.
speed double

50

200

500

1000

 The speed/bandwidth supported by this profile.
unit string MB Unit of the speed/bandwidth supported by this profile.
description string JohnDoe Testing Description of the service profile.
state string APPROVED The state of the service profile.
createdDate string 2018-12-07T13:31:58.525Z The date on which the service profile was created.
createdBy string JohnDoe The username of the user who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The most recent date that the service profile was updated.
lastUpdatedBy string JohnDoe The username of the user who last updated the service profile.
createdByFullName string John Doe The name of the user who created the service profile.
lastUpdatedByFullName string John Doe The name of the user who last updated the service profile.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the service profile.
updatedByEmail string JohnDoe@equinix.com The email ID of the user who last updated the service profile.
organizationName string John-Doe-Corp Organization name associated with the service profile.
allowHighAvailability boolean false Indicates whether the profile supports redundant connections.
allowAuthorizationKeyReUse boolean false  
allowSecondaryLocation boolean false  
private boolean

true

false

 Indicates whether this is a private profile. Unlike public profiles such as AWS/Azure/Oracle/Google, etc, users can only create connections to private profiles after the seller has granted permissions.
features object   An object containing feature-related information such as cloudReach, testProfile, etc.  
cloudReach boolean

true

false

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

true

false

 Indicates whether 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 {uuid}

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

 

The serviceprofiles API returns the details of a given layer 2 service 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 retrieve the seller profile details for the ID 9da3f720-6982-4c40-aa80-af3aad5852a1 and a JSON response containing details of a sample seller profile named John-Doe Demo. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles/9da3f720-6982-4c40-aa80-af3aad5852a1"

-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": "9da3f720-6982-4c40-aa80-af3aad5852a1",
    "name": "JohnDoe_TEST_Profile",
    "requiredRedundancy": false,
    "connectionNameLabel": "Connection",
    "equinixManagedPortAndVlan": false,
    "apiAvailable": false,
    "allowOverSubscription": false,
    "vlanSameAsPrimary": false,
    "tagType": "CTAGED",
    "enableAutoGenerateServiceKey": false,
    "onProfileApprovalRejectNotification": [
        "JohnDoe@equinix.com"
    ],
    "onBandwidthThresholdNotification": [
        "JohnDoe@equinix.com"
    ],
    "onVcApprovalRejectionNotification": [
        "JohnDoe@equinix.com"
    ],
    "ports": [
        {
            "id": "8e638dbf-1713-7130-64e0-30ac094f85f6",
            "sellerRegion": null,
            "sellerRegionDescription": null,
            "metroCode": "SV",
            "inTrail": null,
            "crossConnectId": null,
            "xa": null
        }
    ],
    "allowCustomSpeed": false,
    "speedFromAPI": false,
    "speedBands": [
        {
            "speed": 50,
            "unit": "MB"
        },
        {
            "speed": 200,
            "unit": "MB"
        },
        {
            "speed": 500,
            "unit": "MB"
        },
        {
            "speed": 1000,
            "unit": "MB"
        }
    ],
    "description": "Testing editing.",
    "state": "APPROVED",
    "createdDate": "2019-08-15T10:19:46.092Z",
    "createdBy": "JohnDoe",
    "lastUpdatedDate": "2019-09-12T02:07:11.156Z",
    "lastUpdatedBy": "JohnDoe",
    "globalCustId": "0018000000S1BpZAAV",
    "createdByFullName": "John Doe",
    "lastUpdatedByFullName": "John Doe",
    "createdByEmail": "JohnDoe@equinix.com",
    "updatedByEmail": "JohnDoe@equinix.com",
    "organizationName": "John-Doe-Corp",
    "allowHighAvailability": true,
    "allowAuthorizationKeyReUse": true,
    "allowSecondaryLocation": true,
    "private": true,
    "features": {
        "cloudReach": true,
        "testProfile": false
    }
}

 

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.
isFirstPage boolean

true

false

 Indicates whether the page being displayed is the first page.
totalCount integer 23 The number of items returned as a response for the API request.
pageSize integer 20 The number of items to be displayed 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.
requiredRedundancy boolean

true

false

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

 

If requireRedundancy is true, the user will either need two different ports (primary port and secondary port) for each connection or one port with two connections (primary and secondary).
connectionNameLabel string JohnDoeConnection The label which the user will see when creating connections.
equinixManagedPortAndVlan boolean

true

false

 Indicates whether the VLAN ID details are managed by Equinix.
apiAvailable boolean

true

false

 Indicates whether the service profile has been integrated via APIs with Equinix for automated provisioning of connections.
allowOverSubscription      
vlanSameAsPrimary boolean

true

false

 Indicates whether the same VLAN can be used for both primary and secondary connections.
tagType string

CTAGED

BOTH

NAMED

 The type of tagging to be used when connecting to this service profile. The default value is CTAGED
enableAutoGenerateServiceKey      
onProfileApprovalRejectNotification string JohnDoe@equinix.com The email id to be notified when the profile gets approved or rejected.
onBandwidthThresholdNotification string JohnDoe@equinix.com The email id to be notified when the port bandwidth exceeds. 
onVcApprovalRejectionNotification string JohnDoe@equinix.com The email id to be notified when an incoming connection is approved or rejected.
ports array   An array containing port information.
id string   The ID of the port
sellerRegion string   The region in which the seller port resides.
sellerRegionDescription string   The description of the seller region.
metroCode string SV The metro code of the port associated with this profile.
inTrail      
crossconnectId      
xa      
allowCustomSpeed boolean

true

false

 Indicates whether the profile allows custom speed/bandwidth when creating connections to this profile.
speedfromAPI string

true

false

 Indicates whether the bandwidth of the connection can be obtained directly from the cloud service provider.
speedBands array   An array containing the speed/bandwidth supported by this profile.
speed double

50

200

500

1000

 The speed/bandwidth supported by this profile.
unit string MB Unit of the speed/bandwidth supported by this profile.
description string JohnDoe Testing Description of the service profile.
state string APPROVED The state of the service profile.
createdDate string 2018-12-07T13:31:58.525Z The date on which the service profile was created.
createdBy string JohnDoe The username of the user who created the service profile.
lastUpdatedDate string 2018-12-07T13:58:28.258Z The most recent date that the service profile was modified.
lastUpdatedBy string JohnDoe The username of the user who last updated the service profile.
createdByFullName string John Doe The name of the user who created the service profile.
lastUpdatedByFullName string John Doe The name of the user who last updated the service profile.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the service profile.
updatedByEmail string JohnDoe@equinix.com The email ID of the user who last updated the service profile.
organizationName string John-Doe-Corp Organization name associated with this service profile.
allowHighAvailability boolean false Indicates whether the profile supports redundant connections.
allowAuthorizationKeyReUse boolean false  
allowSecondaryLocation boolean false  
private boolean

false

 Indicates whether this is a private profile. Unlike public profiles such as AWS/Azure/Oracle/Google, etc, users can only create connections to private profiles after the seller has granted permissions.
features object   An object containing feature-related information such as cloudReach, testProfile, etc.  
cloudReach boolean

true

false

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

true

false

 Indicates whether 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 serviceprofiles validateIntegrationId {integrationId}

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

 

The validateIntegrationId API validates a layer 2 API integration ID and returns the regions associated with this ID. 

 

If you are unaware of your integration ID, contact your local Equinix Service Desk.

 

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 API integration ID and its respective JSON response. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles/validateIntegrationId/Demo-01"

-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
IntegrationID Yes string Sample-01   API Integration ID.

 

{

    "redundancy": "REDUNDANT",

    "message": "Demo API integration",

    "state": "VALID",

    "sellerRegions": [
        {
            "interconnectionRegion": "AMER",
            "regionData": [
                {
                    "key": "us-west-1",
                    "description": "US West N.California"
                }
            ]
        },
        {
            "interconnectionRegion": "APAC",
            "regionData": [
                {
                    "key": "ap-southeast-1",
                    "description": "Asia Pacific - Singapore"
                }
            ]
        },
        {
            "interconnectionRegion": "EMEA",
            "regionData": [
                {
                    "key": "eu-west-2",
                    "description": "EU - London"
                }
            ]
        }
    ],
    "metadata": []
}

 

The description of the response payload is as follows:

 

Field Name Type Example Description
redundancy string

SINGLE

REDUNDANT

 The type of redundancy associated with the integration ID.
message string Sample API integration Description of the API.
state string

VALID

INVALID

 Indicates whether the submitted key is valid or invalid.
sellerRegions array[objects]  

An array containing all the regions associated with the integration ID. 
metadata array    

 

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

 


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



Term, Abbreviations, Acronyms Description
2N A redundancy model which ensures that every component has a power backup such that the data center has no single point of failure.
A  Amp, a unit of electrical current.
AC

See Alternating Current (AC). 
ACAE See Air Conditioning Airflow Efficiency (ACAE). 
Access Enrollment Equinix Customer Portal requires a security access assignment. You can request "grant access" or request "remove access".
Access Token A credential used to communicate with the API.
ACL See Access Control List (ACL).
Access Control List (ACL)

The list used by customers to enable and communicate site access authorization of approved employees and third-party vendors. Customers can maintain their ACLs via GCP/ECP or by contacting the Equinix Global Service Desk (GSD).
Additional Interconnection Products These additional interconnection services cover cabling services such as Intra Facility Cabling (IFC) and Patch Cable Installations. 
Aggregator On Enterprise Cloud Exchange (ECX), aggregators are Network Service Providers (NSPs) and Managed Service Providers (MSPs) who provide multi-tenant services. Aggregators are both buyers of ECX service from Equinix and sellers of value-added services over ECX to their end customers.
AHU Air Handling Unit
Air Conditioning Airflow Efficiency (ACAE) The amount of heat removed per standard cubic foot of airflow per minute.
Air Mixing The unintended mixing of cold and hot air.
Airside Economizer A device consisting of fans, ducting and a control which utilizes outside air directly to cool the data center when environmental conditions allow. Air is typically filtered, brought into existing distribution system and then exhausted back to the atmosphere. 
Aisle

The open space between rows of racks. Best practice dictates racks should be arranged with consistent orientation of front and back to create ‘cold' and ‘hot' aisles.
Alternating Current (AC) The designation given to power that is delivered in the form of a sinusoidal wave form. AC won out over DC as the preferred method of delivering and using power in the industrial age due to the ease of voltage transformation using static devices (transformers).
AM Account Manager
AMER Americas (United States, Canada, Brazil)
AMS Asset Management System
AP Asia Pacific, also known as APAC

API

 Application Programming Interface
APAC Asia Pacific, also known as AP
ARD Alternate Resolution Date
ASHRAE  American Society of Heating, Refrigerating and Air Conditioning Engineers (ASHRAE) is an international technical society organized to advance the arts and sciences of air management.
A-side The Ordering Customer Point.
A-side Demarc The Ordering Customer Demarcation Point.
Assets All products pertaining to interconnection and colocation installation services. For a full list of assets, refer to List of Assets under the Appendix section.
ASTS Automatic Static Transfer Switch
Authentication Key The Authentication Key is a unique identifier authorizing Equinix to provision a connection towards the CSP. This Key usually contains alphanumeric characters. Note: to Equinix, an Authentication Key is a generic term and is not encrypted on ECX. Cloud Service Providers might use a different name to refer to the same key. For example: Azure ExpressRoute calls the authorization key the “service key” while AWS calls it the “account ID.”
Authorization key The authorization key typically contains alpha-numeric characters and is a unique identifier authorizing Equinix to provision a connection towards the CSPNote: To Equinix, authorization key is a generic term and is NOT encrypted on ECX. CSPs might use a different name to refer to the same key. For example: Azure ExpressRoute calls the authorization key the “service key” while AWS calls it the “account ID”
BACnet A data communication protocol for building automation and control networks.
BAS Building Automation System
BCI Business Contact Information
BCM Branch Circuit Monitoring
BCTR See Business Continuity Trading Room (BCTR).
BGP Border Gateway Protocol. A standardized exterior gateway protocol designed to exchange routing and reachability information between autonomous systems on the internet.
BGP Session A routing session configured between two peers using the BGP. For standards reference, please see http://www.ietf.org/rfc/rfc4271.txt
BICSI Building Industry Consulting Service International
Blanking Panel A device mounted in unused U spaces in a rack that restricts recirculation airflow, also called blanking or filler plates.
BMMR See Building Meet Me Room (BMMR).
BMR Biometric Reader
BMS Building Management System, synonymous with BAS, AMS and other computer-based tools used to manage data center assets.
BOM Bill of Material
Branch Circuit Monitoring (BCM) A monitoring system used to record and monitor an individual electrical circuit. Typical parameters that are monitored include amperage, voltage, power factor, apparent power (volt-amps), real power (watts) and energy usage (watt-hours). The branch circuit is typically defined to be the circuit fed by a single breaker or 3 phase set of breakers in a multi breaker panel.
Building Meet Me Room (BMMR)

A Building Meet Me Room (BMMR) is an MMR within the same building where an Equinix IBX customer can connect with a non-Equinix IBX customer. 

For more information, see Extended cross connects in the Cross Connects Data Sheet.
Business Continuity Trading Room (BCTR) A dedicated space that allows customers business recovery and continuity in the event of a crisis.

For more detailed information, see Business Continuity Trading Rooms.
BTU British Thermal Unit, a unit of energy. 1kWh = 3412BTU. Cooling equipment capacity is commonly specified in BTU/hr.
Buyer A buyer is a user who connects to an available service through ECX. A buyer can be an enterprise end customer of the seller service or an aggregator, managed service provider, network service provider or system integrator company that bundles its service offerings with ECX.
BYOL Bring Your Own License (BYOL) means that you’ve already procured a license from the vendor and will enter it into the NE portal to activate the device. There are no charges associated with this license type since your licensing arrangement is directly with the vendor.
Bypass Airflow Conditioned air that does not reach computer equipment. With fixed speed fans (common in DX equipment), some bypass air is inevitable and without containment, some bypass air is prudent. Unintended bypass air can occur by escaping through cable cut-outs, holes under cabinets, misplaced perforated tiles or holes in the computer room perimeter walls.
C Degrees Celsius
C/H Cooling/Heating
CAB See Cabinet (CAB).
Cabinet (CAB)

A closed structure inside our data centers that houses servers typically made of metal with rails, grounding studs, interior shelving, etc. Cabinets house the customer's equipment within a private cage.

For more information on Equinix cabinets, see Cages and Cabinets.
CAC See Cold Aisle Containment (CAC). 
CADE Corporate Average Data Center Efficiency.
Cage

A cage is a secluded, secure area within a data center where customers install cabinets and power circuits. The enclosure subdivides colocation space within a data center using mesh walls, a door, security panels, etc.

For more information on Equinix cabinets, see Cages and Cabinets.
CapEx Capital Expense, the cost of purchasing capital equipment.
Campus Cross Connect  

A cross connect type that allows the customer to connect to a service provider in a different IBX no further than 10km away using single-mode fiber. Campus cross connects are a subset of standard cross connects.

For more information, see Cross Connects Data Sheet.
Carbon Footprint A measurement of the volume of Carbon Dioxide generated by business operations, units are commonly metric tons.
Carbon Usage Effectiveness (CUE) A metric defined by the Green Grid, which is a measure of data center sustainability in terms of data center specific carbon emissions. CUE is calculated by dividing the “total CO2 emissions caused by total data center energy” by the “energy consumption of the IT computing equipment”. An alternative way to calculate CUE is by multiplying the data center’s annual PUE by the Carbon Emissions Factor for the region as determined by the EPA. The units of CUE are kilograms of carbon dioxide per kilowatt-hour.
CC See Cross Connect (CC). 
CFA Carrier Facilities Assignment or Circuit Facility Assignment
CFD Computational Fluid Dynamics, a numerical analysis technique commonly used in the analysis of airflow in data centers.
CFM Cubic Feet per Minute, a unit of flow rate, commonly used to specify airflow.
CFR Capacity Feasibility Review
Chiller A unit consisting of a compressor, a condensing section and an expansion section. The condensing and expansion sections nearly always have water or glycol as the heat transfer agent to the rest of the system; primary water/glycol on the condensing side and secondary water on the expansion side.
Close Coupled Cooling Cooling technology that is installed adjacent to server racks, minimizing the path that air must flow from the cooling unit through the IT equipment and back to the cooling unit.
Cloud Exchange Port A type of network port that connects customer to leading cloud service providers (CSP) on the Equinix Cloud Exchange Fabric (ECX Fabric™).
CMR Critical Maintenance Request
CO Change Order
CoE See Coefficient of Effectiveness (COE). 
Coefficient of Effectiveness (COE) Uptime Institute metric based on the Nash-Sutcliffe model efficiency coefficient.
Coefficient of Performance (COP) Used to rate the effectiveness of heat pumps or cooling units. It is the ratio of the load on a cooling unit and the energy that it uses.
Cold Aisle An aisle where rack fronts face into the aisle that cool air is directed to.
Cold Aisle Containment (CAC) A system that directs cool air from air conditioning equipment to the inlet side of racks in a highly efficient manner.
Cold Spot An area where ambient air temperature is below desired levels. Typically caused by ineffective airflow management necessitating a temperature setpoint lower than that which would be required with proper airflow management.
Colo See Colocation (Colo).
Colocation (Colo) A practice in which many different companies or "tenants" share a data center building for economic efficiencies, as well as to digitally interconnect with other companies within the same facility or campus. 
Component/microservice A piece of an overall solution that can be built individually or as part of a larger end-to-end solution
Computer Room Air Conditioner (CRAC) CRAC (pronounced crack) uses refrigerant and a compressor. Cooling of the air in the data center is accomplished by airflow over the evaporation coils where the refrigerant is being "directly expanded" (see DX).
Compute Compute refers to the resources or assets necessary to run a device in the ENE platform. In most ways, the ENE platform is an infrastructure as a service platform underneath, but we typically do not ask customers to get involved in that aspect of the platform. To run efficiently, each device and/or service requires some pre-determined amount of compute. Equinix has thoroughly tested each device and service with the vendor before offering it to the public. This testing ensures that the amount of compute selected on the user's behalf is already optimized to run smoothly with the vendor's recommendations. Customers do not need to customize or tweak the compute in most cases.
Connection Connection is a general term that refers to any solution that results in the ability to pass data from one point to another. Connections can be made with Layer 2 or Layer 3 technology, may involve several parts or components and can be created from the portal or with APIs in a variety of ways.
Containment Using either long curtains or rigid plastic to maintain a physical barrier between a hot and cold aisle. Keeping warm exhaust air away from the intake of the server racks is a crucial part of making any data center more efficient.
Cooling Tower A device which cools water via the direct evaporation of some of the water. Water is pumped into the top of the cooling tower and allowed to run down over the fill, typically pads or strips into a sump at the bottom of the cooling tower. Air is drawn in from the sides over the fill by fans in the top of the tower, evaporating some of the water which cools the remaining water. The temperature of the water in the sump is controlled by varying the speed of the fans. The water in the sump is then used to cool the condensing section of a chiller or to cool the secondary loop directly via a heat exchanger (see water side economizer).
COP See Coefficient of Performance (COP). 
CR Computer Room
CRAC See Computer Room Air Conditioner (CRAC).
CRAH Computer Room Air Handler (pronounced craw) which uses chilled water passing through a heat exchanger to cool air flowing over the heat exchanger.
CRD Customer Requirements Document
Critical Load Computer equipment whose uptime is critical, typically supported by a UPS.
CRM Customer Relations Manager
Cross Connect (CC)

A cross connect is a point-to-point cable link between two customers in the same IBX. With cross connects customers receive a fast, convenient and affordable integration with business partners and service providers within the Equinix digital ecosystem. They also get highly reliable, extremely low-latency communication, system integration and data exchange

For more information on cross connects, see Equinix Cross Connects.
CSI Cold Supply Infiltration index, quantifies the amount of hot air mixing with cold inlet air prior to entering the rack.
CSM Customer Success Manager (formerly known as client services manager)
Cloud Service Provider CSP A Cloud Service Provider (CSP) is a company that offers some type of cloud services to other businesses or individuals. In this context, that can include: cloud computing, cloud storage, cloud content delivery network (CDN) and more. Typical CSPs include Infrastructure as a Service (IaaS), Software as a Service (SaaS) and Platform as a Service (PaaS).
CT See Current Transformer (CT).
CUE See Carbon Usage Effectiveness (CUE). 
Current Transformer (CT) A device used to transform electrical current from one level to another with a specific ratio. For example, a 5000:5 current transformer transforms current on the primary side to current on the secondary side with a ratio of 1000:1. CTs are typically used to transform large currents to much smaller currents so that standard metering equipment can be used on a variety of circuits by measuring the sec