API - Connect to IBM Cloud Direct Link 2.0
Establish a connection with IBM Cloud™ Direct Link 2.0 to connect your IBX colocated assets to your IBM Cloud resources.
Identify Your IBM Account ID
Log in to the IBM Cloud console and select Manage > Account to locate your IBM account ID.
Fabric API Prerequisites
-
Authenticate - Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication. Refer to API Authentication for instructions on how to call OAuth API to validate and authenticate your credentials.
-
Determine Your A-side Information. Either:
- Retrieve your Equinix Fabric ports information using the Get All Ports API request.
OR
- Determine your Network Edge device information. You need a provisioned Equinix Virtual Device/Redundant Devices/Cluster with a registered license. Check your available virtual devices and clusters by calling Get Virtual Devices or Get Virtual Device {uuid}. You may choose any available interface on the device for your connection. However, Equinix will select an interface if you do not specify one.
-
Choose the Z-side metro location. Use the Get All Metros API request to find all metros where Equinix Fabric is available and determine destination location.
-
Identify the service profile. Use the Retrieve Service Profiles API request to search for a specific service profile or use the Get Service Profiles API request to list all available service profiles, and identify the profile you want to connect to.
Connecting to IBM Cloud Direct Link 2.0 from a DOT1Q port
To create a connection from your DOT1Q port to IBM Cloud Direct Link 2.0, send a POST request to the /fabric/v4/connections endpoint. Specify your connection's configuration details in the body of the request.
| POST /fabric/v4/connections | |
|---|---|
| Method | POST |
| Endpoint | /fabric/v4/connections |
| Headers | Authorization, Content-Type |
| Path Parameters | Not applicable |
| Query Parameters | Not applicable |
| Body Parameters | type, name, order, bandwidth, redundancy, aSide, zSide, additionalInfo, notifications |
Sample cURL Request:
curl -X
POST 'https://api.equinix.com/fabric/v4/connections'
-H 'content-type: application/json'
-H 'authorization: Bearer <token>'
-d '{
"type": "EVPL_VC",
"name": "Conn-1",
"order": {
"purchaseOrderNumber": "1-129105284100"
},
"bandwidth": 1000,
"redundancy": {
"priority": "PRIMARY"
},
"aSide": {
"accessPoint": {
"type": "COLO",
"port": {
"uuid": "a867f685-41b0-1b07-6de0-320a5c00abdd"
},
"linkProtocol": {
"type": "DOT1Q",
"vlanTag": 1001
}
}
},
"zSide": {
"accessPoint": {
"type": "SP",
"profile": {
"uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
},
"location": {
"metroCode": "SV"
},
"authenticationKey": "xx-xxx-xx",
"sellerRegion": "us-west-1"
}
},
"additionalInfo": [
{
"key": "ASN",
"value": "12345"
},
{
"key": "CER IPv4 CIDR",
"value": "11.1.1.10/30"
},
{
"key": "IBM IPv4 CIDR",
"value": "11.1.1.10/30"
}
],
"notifications": {
"type": "ALL",
"emails": [
"test@equinix.com",
"test2@equinix.com"
]
}
}'
The parameters included in the request body are specific to this example. For a full list of parameters and their descriptions, see the API Reference.
Sample Response:
{
"href": "https://api.equinix.com/fabric/v4/connections/3a58dd05-f46d-4b1d-a154-2e85c396ea62",
"type": "EVPL_VC",
"uuid": "3a58dd05-f46d-4b1d-a154-2e85c396ea62",
"name": "Conn-1",
"state": "PROVISIONING",
"order": {
"purchaseOrderNumber": "1-129105284100",
"billingTier": "Up to 1 Gbps"
},
"bandwidth": 1000,
"redundancy": {
"group": "m167f685-41b0-1b07-6de0-320a5c00abeu",
"priority": "PRIMARY"
},
"aSide": {
"accessPoint": {
"type": "COLO",
"port": {
"href": "https://api.equinix.com/fabric/v4/ports/a867f685-41b0-1b07-6de0-320a5c00abdd",
"type": "XF_PORT",
"uuid": "a867f685-41b0-1b07-6de0-320a5c00abdd"
},
"linkProtocol": {
"type": "DOT1Q",
"vlanTag": 1001
}
}
},
"zSide": {
"accessPoint": {
"type": "SP",
"profile": {
"href": "https://api.equinix.com/fabric/v4/services/serviceProfiles/20d32a80-0d61-4333-bc03-707b591ae2f5",
"type": "L2_PROFILE",
"uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
},
"location": {
"href": "https://api.equinix.com/v4/metros/SV",
"metroCode": "SV",
"region": "AMER"
},
"authenticationKey": "xx-xxx-xx",
"sellerRegion": "us-west-1"
}
},
"additionalInfo": [
{
"key": "ASN",
"value": "12345"
},
{
"key": "CER IPv4 CIDR",
"value": "11.1.1.10/30"
},
{
"key": "IBM IPv4 CIDR",
"value": "11.1.1.10/30"
}
],
"notifications": [
{
"type": "ALL",
"emails": [
"test@equinix.com",
"test2@equinix.com"
]
}
],
"operation": {
"equinixStatus": "PROVISIONING",
"providerStatus": "PROVISIONING"
},
"changeLog": {
"createdDateTime": "2021-07-15T19:30:29.526Z"
}
}
Response payload includes configuration parameters defined in the request body. For a full list of possible parameters and their descriptions, see the API Reference.
Connecting to IBM Cloud Direct Link 2.0 from a QINQ port
To create a connection from your QINQ port to IBM Cloud Direct Link 2.0, send a POST request to the /fabric/v4/connections endpoint. Specify your connection's configuration details in the body of the request.
| POST /fabric/v4/connections | |
|---|---|
| Method | POST |
| Endpoint | /fabric/v4/connections |
| Headers | Authorization, Content-Type |
| Path Parameters | Not applicable |
| Query Parameters | Not applicable |
| Body Parameters | type, name, order, bandwidth, redundancy, aSide, zSide, additionalInfo, notifications |
Sample cURL Request:
curl -X
POST 'https://api.equinix.com/fabric/v4/connections'
-H 'content-type: application/json'
-H 'authorization: Bearer <token>'
-d '{
"type": "EVPL_VC",
"name": "Conn-1",
"order": {
"purchaseOrderNumber": "1-129105284100"
},
"bandwidth": 1000,
"redundancy": {
"priority": "PRIMARY"
},
"aSide": {
"accessPoint": {
"type": "COLO",
"port": {
"uuid": "a867f685-41b0-1b07-6de0-320a5c00abdd"
},
"linkProtocol": {
"type": "QINQ",
"vlanCTag": 1001,
"vlanSTag": 1002
}
}
},
"zSide": {
"accessPoint": {
"type": "SP",
"profile": {
"uuid": "20d32a80-0d61-4333-bc03-707b591ae2f5"
},
"location": {
"metroCode": "SV"
},
"authenticationKey": "xx-xxx-xx",
"sellerRegion": "us-west-1"
}
},
"additionalInfo": [
{
"key": "ASN",
"value": "12345"
},
{
"key": "CER IPv4 CIDR",
"value": "11.1.1.10/30"
},
{
"key": "IBM IPv4 CIDR",
"value": "11.1.1.10/30"
}
],
"notifications": {
"type": "ALL",
"emails": [
"test@equinix.com",
"test2@equinix.com"
]
}
}'
The parameters included in the request body are specific to this example. For a full list of parameters and their descriptions, see the API Reference.
Connecting to IBM Cloud Direct Link 2.0 from a Network Edge Device
To create a connection from your Network Edge device to IBM Cloud Direct Link 2.0, send a POST request to the /fabric/v4/connections endpoint. Specify your connection's configuration details in the body of the request.
| POST /fabric/v4/connections | |
|---|---|
| Method | POST |
| Endpoint | /fabric/v4/connections |
| Headers | Authorization, Content-Type |
| Path Parameters | Not applicable |
| Query Parameters | Not applicable |
| Body Parameters | type, name, order, bandwidth, redundancy, aSide, zSide, additionalInfo, notifications |
Sample cURL Request:
curl -X
POST 'https://api.equinix.com/fabric/v4/connections'
-H 'content-type: application/json'
-H 'authorization: Bearer <token>'
-d '
{
"type": "EVPL_VC",
"name": "port2ibm2-vvv-0425f",
"bandwidth": "50",
"aSide": {
"accessPoint": {
"type": "VD",
"virtualDevice": {
"type": "EDGE",
"uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
},
"zSide": {
"accessPoint": {
"type": "SP",
"profile": {
"type": "L2_PROFILE",
"uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"location": {
"metroCode": "SV"
},
"authenticationKey": "XXXXXXXXXX",
"sellerRegion": "San Jose 2"
}
},
"additionalInfo": [
{
"key": "ASN",
"value": 12345
},
{
"key": "BGP_CER_CIDR",
"value": "172.16.0.17/30"
},
{
"key": "BGP_IBM_CIDR",
"value": "172.16.0.18/30"
},
{
"key": "Global",
"value": false
}
],
"project": {
"projectId": "16799d66-ef43-445c-ba29-d17522d8a137"
},
"order": {
"purchaseOrderNumber": "1-129105284100"
},
"notifications": [
{
"type": "ALL",
"emails": [
"x@gmail.com"
]
}
]
}
'
The parameters included in the request body are specific to this example. For a full list of parameters and their descriptions, see the API Reference.
Sample Response:
{
"type": "EVPL_VC",
"href": "https://api.equinix.com/fabric/v4/connections/0175e136-8be7-4b04-8d57-c33c20555501",
"uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "port2ibm2-vvv-0425f",
"operation": {
"providerStatus": "PROVISIONING",
"equinixStatus": "PROVISIONING"
},
"order": {
"purchaseOrderNumber": "1-129105284100",
"billingTier": "Up to 50 MB"
},
"notifications": [
{
"type": "ALL",
"emails": [
"x@gmail.com"
]
}
],
"changeLog": {
"createdBy": "fabricamcrh1",
"createdByFullName": "XXXXX XXXXXX",
"createdByEmail": "x@gmail.com",
"createdDateTime": "2024-04-25T20:41:37.805Z",
"updatedBy": "fabricamcrh1",
"updatedByFullName": "XXXXXX XXXXXX",
"updatedByEmail": "x@gmail.com",
"updatedDateTime": "2024-04-25T20:41:37.805Z"
},
"bandwidth": 50,
"redundancy": {
"group": "d1f11356-91ca-4550-8488-ba434a771e09",
"priority": "PRIMARY"
},
"aSide": {
"accessPoint": {
"interface": {
"uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"id": 8,
"type": "CLOUD"
},
"location": {
"metroCode": "DC"
},
"virtualDevice": {
"uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"type": "EDGE"
}
}
},
"zSide": {
"accessPoint": {
"location": {
"metroCode": "SV"
},
"profile": {
"href": "https://api.equinix.com/fabric/v4/serviceProfiles/e092ed47-63d2-4f4a-87a0-82e3b08eefe5",
"type": "L2_PROFILE",
"name": "IBM Cloud Direct Link 2",
"uuid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"sellerRegion": "San Jose 2",
"authenticationKey": "XXXXXXXXXXXXXXXXXXX"
}
}
}
Response payload includes configuration parameters defined in the request body. For a full list of possible parameters and their descriptions, see the API Reference.
Monitoring Connection Status
Send a GET request to the fabric/v4/connections/{connectionId} endpoint to monitor connection status.
equinixStatusattribute values | providerStatusattribute values | IBM Direct Link status | Description |
|---|---|---|---|
PROVISIONING | PROVISIONING | - | Connection request has not been sent to IBM yet. |
PENDING_PROVIDER_VLAN | PENDING_APPROVAL | Create approval pending | The connection awaits for approval. |
PROVISIONED | PROVISIONING / PROVISIONED | Create in progress | Connection establishment in progress. |
PROVISIONED | PROVISIONED | Provisioned | Connection established. |
Accepting the Connection
Log in to the IBM Cloud console and navigate to the IBM Cloud Direct Link Exchange page to review and accept the pending connection.