Connect to IBM
End users can create connections to IBM Direct Link using either a Dot1q port or a QinQ port.
The following video shows how to connect to IBM Direct Link using Equinix Fabric APIs.
Click here to download the postman scripts shown in this demo.
Layer 2 Connection to IBM
Step 1: Retrieve IBM Account Info
Locate your IBM account ID using the IBM cloud portal.
The IBM Account ID is essential for creating an IBM Direct Link connection.
Refer https://www.ibm.com/cloud/direct-link/details for instructions on how to signup for IBM Direct Link.
Step 2: Create Connection
2a) Authenticate
Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.
Refer to Generating Client ID and Client Secret under the Getting Access Token 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 Fabric, contact your local Equinix Service Desk.
2b) Get the Port
Retrieve your allocated Equinix Fabric 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 Equinix 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 Endpoint | /ecx/v3/l2/connections |
| Headers | Authorization, Content-Type |
| Query Parameters | Not applicable |
| Body Parameters | primaryName, primaryPortUUID, primaryVlanSTag, primaryVlanCTag, profileUUID, authorizationKey, speed, speedUnit, notifications [...], purchaseOrderNumber, sellerRegion, sellerMetroCode, additionalInfo[...] |
The POST connections API creates a layer 2 connection between your port and the destination service profile. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.
If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens section under the Getting Access Token.
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 GET 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@example.com"
],
"purchaseOrderNumber": "1234567890",
"primaryPortUUID": "7f891d3b-973e-73e0-bae0-30ac1885197a",
"primaryVlanSTag": "774",
"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@example.com"
],
"purchaseOrderNumber": "0987654321",
"primaryPortUUID": "99991d3b-9750-7500-bae0-30ac1885197a",
"primaryVlanSTag": "774",
"primaryVlanCTag": "775",
"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 | User-defined name of the primary connection. Supply an alpha-numeric string, which can include hyphens and underscores ('-' & '_') as special characters (no other special characters are allowed). Max Length: 24 characters | |
| primaryPortUUID | Yes | string | 99991d3b-9750-7500-bae0-30ac1885197a | Unique Equinix-assigned ID of the buyer's primary port from where the connection originates. | |
| primaryVlanSTag | Yes | integer | 774 | 2 - 4094 | S-Tag/Outer-Tag of the primary connection. Range: 2 - 4094. |
| primaryVlanCTag | Yes | integer | 775 | 2 - 4094 | C-Tag/Inner-Tag of the primary connection. Range: 2 - 4094 |
| profileUUID | Yes | string | 999552b-39b0-49ea-a232-005088dc9c86 | Unique Equinix-assigned ID of the provider's service profile. | |
| authorizationKey | Yes | string | 123456789012 | Authorization Key provided by IBM, such as the IBM Service Key. | |
| speed | Yes | integer | 50 | Speed/bandwidth to be allocated to the connection. | |
| speedUnit | Yes | string | MB | MB | Unit of the speed/bandwidth to be allocated to the connection. Values: Either MB or GB. |
| notifications | Yes | arra. y[string] | JohnDoe@example.com |
| A list of email addresses that are notified when there are any updates on this connection. Example: ["user@example.com", "user2@example.com"] |
| purchaseOrderNumber | Yes | string | 0987654321 | This optional field links the purchase order to the connection on Equinix. This link is reflected on the invoice. | |
| sellerMetroCode | Yes | string | SV | The metro code that denotes the connection’s destination (Z side). If sellerMetroCode is empty, the value defaults to the metro code of the port. | |
| additionalInfo | Yes | array [string] | An array containing additional information. | ||
| name | Yes | string | global | Indicates whether the data center is global or local 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 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 GET Connections{uuid}.
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 GET Connections{uuid}. 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 DELETE Connections{uuid} 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. | |
Step 3: Accept Connection
Accept the virtual connection using IBM Direct Link portal.
Refer to https://www.ibm.com/cloud/direct-link/details for instructions on how to accept the connection using IBM Direct Link port