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 OAuth2Access 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 watch a video on how to connect to AWS Direct Connect using Equinix Cloud Exchange Fabric APIs. 

 


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

 


body: 
Step 1: Retrieve AWS Account Info

Locate your AWS account ID using the AWS Management console.

 

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

 

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

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under 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 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 you would like to allocate to the connection.
speedUnit Yes string MB MB Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

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

 

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 Indicates the status of the PATCH API call.
primaryConnectionID string primaryConnectionId: "9999a8-0e07-44d0-944c-88a25d8d28f7" Indicates the primary connection ID of the connection that was accepted.

 

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

 

Refer

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

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

 


body: 

Connect to Microsoft

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

 

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

 


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

 

 


body: 
Step 1: Retrieve Microsoft Service Key

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

 

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

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key 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 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 you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  JohnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string     An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
secondaryName Yes string JohnDoe2_Azure_QinQ   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer secondary port from which the 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 you would like to set up with Azure Express Route.
primaryZSideVlanCTag Yes integer 558   C-Tag/Inner-Tag of the primary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")
secondaryZSideVlanCTag Yes integer 542   C-Tag/Inner-Tag of the secondary connection on the Z side. This is only applicable for "Manual" peering. (i.e. namedTag  = "Manual")

 

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

 

Port Type (A-side) Maximum Number Of Connections

Peering Type (indicated by namedTag field)

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

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

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 watch a video on how to connect to GCPI using Equinix Cloud Exchange Fabric APIs. 

 


body: 
How to establish an L2 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 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 you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

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

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 watch a video on how to connect to Oracle FastConnect using Equinix Cloud Exchange Fabric Portal. 

 


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

 


body: 
Step 1: Retrieve Oracle OCID

Obtain your Oracle OCID using the Oracle portal.

 

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

 

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

 


body: 
Step 2: Create Connection

2a) Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under 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 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 you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

Once the POST Connections API is successfully called, you may check the status of the connection using the 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 an L2 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 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 you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the authorization key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

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

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 an L2 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://cloud.ibm.com/docs/infrastructure/direct-link?topic=direct-link-how-to-order-ibm-cloud-direct-link-connect 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

 

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 primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

2 - 4094

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

2 - 4094

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

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber Yes string 0987654321   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
sellerRegion Yes string us-west-1   Indicates the region in which the seller port resides.
sellerMetroCode Yes string SV   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code. 
additionalInfo          
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://docs.aws.amazon.com/directconnect/latest/APIReference/API_Connection.html 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://cloud.ibm.com/docs/infrastructure/direct-link?topic=direct-link-how-to-order-ibm-cloud-direct-link-exchange&cm_sp=Cloud-Product-_-OnPageNavLink-IBMCloudPlatform_IBMCloudInternetServices-_-DirectLink_Providers_Connect for instructions on how to accept the connection using IBM Direct Link portal.

 


body: 

Connect to Enterprises

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

 

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

 


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

 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under 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 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 you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

Once the POST Connections API is successfully called, you may check the status of the connection using the 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 an L2 redundant enterprise connection?

 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under 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 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 you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  johnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 123456789   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
sellerRegion No string us-sv   An optional field that needs to be passed if requested by the service profile you intend to connect to.
secondaryName Yes string JohnDoe_QinQ_To_QinQ2   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer secondary port from which the 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 an L2 non-redundant self-connection?

 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under 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 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 you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

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

 

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

 

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

Connection request has been sent for auto approval.

 

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

Connection establishment in progress.
PROVISIONED AVAILABLE Connection established.
 

 

 

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

 

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

DEPROVISIONING

 AVAILABLE

Connection disbandment in progress.
DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 

 


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

 

 

 


body: 
Step 1: Authenticate

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

 

Refer to Generating a Client ID and Client Secret key under 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 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 you would like to allocate to the connection. If you do not know the speed, you can call the validateAuthorizationkey API and query using the ExpressRoute service key to obtain the speed.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array  johnDoe@equinix.com

 

 An array of email ids you would like to notify when there are any updates on your connection. Example Object: ["user@organization.com", "user@eu.company.com"]
purchaseOrderNumber No string 123456789   An optional field to link the purchase order numbers to the connection on Equinix which would get reflected on the invoice.
authorizationKey No string     An optional field based on the service profile you want to connect to. 
sellerMetroCode Yes string DC   Provider location where you would like to connect. If the sellerMetroCode is empty, the metro code of the port is set as the default seller metro code.  
sellerRegion No string us-sv   An optional field that needs to be passed if requested by the service profile you intend to connect to.
secondaryName Yes string JohnDoe_QinQ_To_QinQ2   Name of the secondary connection - An alpha-numeric 24 characters string which can include only hyphens and underscores ('-' & '_').
secondaryPortUUID Yes string 7f891d3b-973d-73d0-bae0-30ac1885197a   Unique identifier of the buyer secondary port from which the 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 an L2 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 service profile. The authorization key is the only header that is passed to this API and a response is received based on the values passed.

 

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

 

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

 

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 primary port from which the connection would get originate.
primaryVlanSTag Yes integer 774

 

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

 

 C-Tag/Inner-Tag of the primary connection - A numeric character ranging from 2 - 4094.
speed Yes integer 50   Speed/Bandwidth you would like to allocate to the connection.
speedUnit Yes string MB   Unit of the speed or bandwidth you would like to allocation to the connection.
notifications Yes array string JohnDoe@equinix.com

 

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

 

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

 

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

 

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

 

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

 

The description of the response payload is as follows:

 

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

 

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

 

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

 

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

Connection request has been sent for auto approval.

 

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

Connection establishment in progress.
PROVISIONED AVAILABLE Connection established.
 

 

 

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

 

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

DEPROVISIONING

 AVAILABLE

Connection disbandment in progress.
DEPROVISIONED NOT_AVAILABLE

Connection deleted.

 

 


body: 
How to 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: 

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: 

GET User Port

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

 

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

 

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

 

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

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

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

 

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

 

The description of the response payload is as follows:

 

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

ADDED

PROVISIONED

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

AMER

EMEA

APAC

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

true

false

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

SV

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

Primary

"Secondary"

The priority of the device (Primary/secondary).

 

Ensure to check if the port is primary or secondary and pass accordingly during connection creation. A port with "Secondary" devicePriority cannot be passed into the primaryPortUUID  attribute during connection creation. 
encapsulation string

Dot1q

QinQ

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

true

false

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

true

false

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

true

false

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

true

false

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

 

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

 


body: 

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 Port Stats

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

 

The Get port stats API retrieves the utilization of inbound and outbound traffic 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 query parameters are as follows:

 

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: 

Layer 2 Buyer APIs


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 GET 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 be originated.

 

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

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

 

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

 

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

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

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

DC

 

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

 

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

 

The description of the response payload is as follows:

 

Field  Name Type Example Description
isLastPage boolean

true

false

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

true

false

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

true

false

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

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

true

false

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

50

200

500

1000

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

true

false

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

CTAGED

BOTH

NAMED

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

true

false

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

true

false

 Indicates whether the profile belongs to your organization.
speedfromAPI string

true

false

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

Dot1q

Qinq

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

true

false

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

true

false

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

true

false

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

 

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

 


body: 

GET L2 Service Profiles Services {uuid}

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

 

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

 

Uuid is an identifier unique for each service profile.

 

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

 

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

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the URL parameter is as follows:

 

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

 

 Identifier of service profile.
 

 

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

 

The description of the response payload is as follows:

 

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

true

false

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

true

false

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

50

200

500

1000

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

true

false

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

CTAGED

BOTH

NAMED

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

true

false

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

true

false

 Indicates whether the profile belongs to your organization.
speedfromAPI string

true

false

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

Dot1q  

Qinq

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

true

false

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

true

false

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

true

false

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

 

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

 


body: 

 GET L2 Validate Authorization Key

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

 

This API validates Authorization or Service key or Account Id to connect to Cloud Service Providers. The participant must first use the Provider consoles to establish a connection and obtain a valid account or service key that is then used to create the connections to CSPs from ECX. Participants may validate their keys using this API. 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 used to denote the metro.
profileId Yes string x1384t22-bbe0-4e43-ax37-95beeg9d254d   The unique identifier of the service profile.
region Yes string AMER

"AMER"

"EMEA"

"APAC"

 Indicates the region in which the port resides.

 

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

 

The description of the response payload is as follows:

 

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

VALID

INVALID

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

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

 

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

 


body: 

GET L2 Buyer Connections

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

 

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

 

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

 

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

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the query parameters are as follows:

 

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

"PROVISIONED"

"DEPROVISIONED"

"PENDING_APPROVAL"

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

 

 The 2 character 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   Can only be used by resellers.
pageNumber No integer 1   The page number of the page which is currently being displayed. 
pageSize No integer 20   The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 

 

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

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

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

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

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

"Dot1q"

"Qinq"

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

Private

Public

Microsoft 

Manual

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

true

false

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

true

false

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

true

false

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

"DEPROVISIONED"

"PROVISIONED"

"PENDING_APPROVAL"

"NOT_AVAILABLE"

"DEPROVISIONING"

"PROVISIONING"

"FAILED"

"PENDING_BGP"

"AVAILABLE"

"OUTOFBANDWIDTH"

"ERROR"

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

DEPROVISIONED

PROVISIONED

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

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

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

true

false

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

true

false

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

 

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

 


body: 

GET L2 Connections {uuid}

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

 

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

 

Uuid is an identifier unique for each connection.

 

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

 

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

 

curl -X

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

-H "content-type: application/json"

-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

 

The description of the URL parameter is as follows:

 

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

 

 Identifier of connection.
 

 

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

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

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

        }
    ],
    "pageNumber": 0
}

 

The description of the response payload is as follows:

 

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

Dot1q

Qinq

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

"Private" 

"Public" 

"Microsoft" 

"Manual"

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

true

false

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

"primary"

"secondary"

 The type of connection.
remote boolean  

true

false

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

true

false

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

MB

GB

 The unit of bandwidth speed.
providerStatus string

DEPROVISIONED

PROVISIONED

PENDING_APPROVAL

NOT_AVAILABLE

DEPROVISIONING

PROVISIONING

FAILED

PENDING_BGP

AVAILABLE

OUTOFBANDWIDTH

ERROR

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

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

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

true

false

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

true

false

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

 

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

 


body: 

DELETE Connections {uuid}

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

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

 

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

 

Uuid is an identifier unique for each connection.

 

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

 

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

 

curl -X

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 Delete API call.
primaryConnectionID string 702d31c4-c66d-49b0-a26c-a9a234e56fsb Indicates the primary connection ID.
 

 

 

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

 

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

 


body: 

Layer 2 Seller APIs


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 L2 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 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 Indicates 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 all 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 to obtain all outgoing L2 connections for user credentials submitted and its JSON response. 

 

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"

 Indicates 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 the response for the 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. The server will return a set of pages with the requested number of items per page. 
content object   An array containing the response data.
buyerOrganizationName string JOHN-DOE-ORG Buyer organization name.
uuid string 006d08e2-788e-4c83-82d3-07b1787644a5 The unique identifier of the connection.
asideEncapsulation string

"Dot1q"

"Qinq"

 The encapsulation of the buyer port (Dot1q or QinQ).
billingTier string Up to 50 MB Billing tier for connection.
createdBy string JohnDoe@equinix.com The username who created the connection.
createdByEmail string JohnDoe@equinix.com The email ID of the user who created the connection.
createdByFullName string JohnDoe The full name of the user who created the connection.
createdDate string 2018-08-30T04:20:36.033Z The date on which the connection was created.
lastUpdatedBy string JohnDoe 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 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 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 Email address of the contact to be notified for any updates on the connection.
metroCode string DC 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   Name of the connection.
namedTag string

Private

Public

Microsoft 

Manual

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

true

false

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

true

false

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

true

false

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

"DEPROVISIONED"

"PROVISIONED"

"PENDING_APPROVAL"

"NOT_AVAILABLE"

"DEPROVISIONING"

"PROVISIONING"

"FAILED"

"PENDING_BGP"

"AVAILABLE"

"OUTOFBANDWIDTH"

"ERROR"

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

DEPROVISIONED

PROVISIONED

 The status of the connection at Equinix's end.
       
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

 

This API retrieves all L2 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 L2 sellers within DC, USA and a JSON response containing details of a sample seller named John-Doe Demo. 

 

curl -X

GET "https://api.equinix.com/ecx/v3/l2/serviceprofiles?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 response for the API request.
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content array   An array containing the response data.
uuid string 97d1850f-4df0-468c-9281-fa7b0dfa2096 The unique identifier of the service profile.
name string John-Doe Demo The name assigned to the service profile.
requiredRedundancy boolean

true

false

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

If requireRedundancy” = true, you would need two ports, a primary port with a primary connection and a secondary port with a secondary connection, or one port and two connections (one primary and one secondary).
connectionNameLabel string JohnDoeConnection This is the label the user will see when creating a connection name for their connection.
equinixManagedPortAndVlan boolean

true

false

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

true

false

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

true

false

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

CTAGED

BOTH

NAMED

 The type of tagging to be used for connections to this service profile. The default value is CTAGED.
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     The ID of the port
sellerRegion     Indicates the region in which the seller port resides.
sellerRegionDescription     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 or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
speedfromAPI string

true

false

 Bandwidth of the cloud service provider for this connection according to the service provider.
speedBands array   An array containing the speeds/bandwidth ranges allowed when creating connections to this profile.
speed double

50

200

500

1000

 Bandwidth speed.
unit string MB Bandwidth speed unit.
description string JohnDoe Testing Description of the profile.
state string APPROVED The state of the 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      
allowAuthorizationKeyReUse      
allowSecondaryLocation      
private boolean

true

false

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

true

false

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

true

false

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

 

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

 


body: 

Get L2 Service Profiles {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

 

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

 

Uuid is an identifier unique for each service profile.

 

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

 

The following screenshots show a sample curl request to 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 response for the API request.
pageSize integer 20 The number of items to be displayed per page. The server will return a set of pages with the requested number of items per page. 
content array   An array containing the response data.
uuid string 97d1850f-4df0-468c-9281-fa7b0dfa2096 The unique identifier of the service profile.
name string John-Doe Demo The name assigned to the service profile.
requiredRedundancy boolean

true

false

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

If requireRedundancy” = true, you would need two ports, a primary port with a primary connection and a secondary port with a secondary connection, or one port and two connections (one primary and one secondary).
connectionNameLabel string JohnDoeConnection This is the label the user will see when creating a connection name for their connection.
equinixManagedPortAndVlan boolean

true

false

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

true

false

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

true

false

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

CTAGED

BOTH

NAMED

 The type of tagging to be used for connections to this service profile. The default value is CTAGED.
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     The ID of the port
sellerRegion      
sellerRegionDescription      
metroCode string SV The metro code of the port associated with this profile.
inTrail      
crossconnectId      
xa      
allowCustomSpeed boolean

true

false

 Indicates whether or not to allow custom bandwidths/speeds to be defined when creating connections to this profile.
speedfromAPI string

true

false

 Bandwidth of the cloud service provider for this connection according to the service provider.
speedBands array   An array containing the speeds/bandwidth ranges allowed when creating connections to this profile.
speed double

50

200

500

1000

 Bandwidth speed.
unit string MB Bandwidth speed unit.
description string JohnDoe Testing Description of the profile.
state string APPROVED The state of the 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      
allowAuthorizationKeyReUse      
allowSecondaryLocation      
private boolean

true

false

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

true

false

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

true

false

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

 

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

 


body: 

 Get L2 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 an L2 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 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

 

Access Token

A credential used to communicate with the API.
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.
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
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.

Cage

A custom build (as per customer’s requirement) and secured mesh enclosure to house multiple cabinets in it.
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).
Component/microservice A piece of an overall solution that can be built individually or as part of a larger end-to-end solution
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.
Cross Connect A Cross Connect is a point-to-point cable link between two customers in the same Equinix IBXdata center. 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

Equinix Cloud Exchange Fabric or ECX Fabric or ECX

Equinix Cloud Exchange Fabric (ECXF) is an advanced software-defined interconnection solution that enables you to directly, securely and dynamically connect to distributed infrastructure and digital ecosystems on platform Equinix via a single port.
End customer/end device/CPE The entity and/or devices managed by that entity that ultimately interact with the services bought over the ECX platform

IBX

Equinix International Business Exchange.

OAuth

 

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

 

Rack

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

 

Refresh Token

 

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

 

 


body: 

Style guide and References

Additional information

 

 

Tips and recommendation 

 

 

Critical information 

 

 

Code snippet

 

 

Output snippet 

 

 

Error information

 

 

Internal Links

 

External Links

 

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

 


body: 

 

 

 Contact us

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


Twitter Feed

About Equinix

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

Developer Platform - Key Highlights

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

Recent News

New grant type "client_credentials" enabled for OAuth 2.0 API.
IBX SmartView Streaming API is now available on Developer Platform
Equinix Customer Portal APIs (Beta) is now available on Playground.
ECX Fabric v3 API is recommended for integration.
New Developer Experience Launched! Let us know your feedback.
 
Copyright © 2018 Equinix. All rights reserved. Terms of Use | Privacy Policy | API Agreement