Edit of Virtual Connect VLAN and/or Bandwidth and/or metadata
Introduction
After a Virtual Connect has been provisioned you can change the following:
Change VLANs
Change Bandwidth
Change Metadata (that is to say, PO Number, Customer Reference and Contract Reference)
This is currently only supported for A to A scenarios, that is to say, where the Account(s) on the A and B side of the Virtual Connect fall under the same parent account.
Supported VLAN changes
The following changes are supported for changing Virtual Connect VLANs.
Please refer to the V2 IX-API open api specification here https://docs.ix-api.net (officially published).
This specification covers the API described in the steps below.
1. Request Client Credentials
(If you already have client credentials skip to step 2.)
Follow the description on this page Requesting IX-API Client Credentials
You shall receive the credentials via separate emails:
EMAIL 1 shall contain client_id, login URL and IX-API URL
EMAIL 2 shall contain client_secret
2. Edit VLAN of a Virtual Connect
Step 1: Use client credentials to generate an access token
Make the following request to generate an access token:
curl --location --request POST 'https://{{login-url}}/connect/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>'
The response is a http 200 OK with response body containing the access token.
{
"access_token": "{YOUR_TOKEN}",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "resource.api resource.ixapi resource.productcatalogapi"
}
The access token in the response shall be used in all subsequent requests.
Authentication
When you make an API call, you need to use an “Authorization” HTTP header to provide your API key, with a “Bearer” prefix. For example:
Authorization: Bearer {YOUR_TOKEN}
Step 2: Read the configuration of the Virtual Connect
Read the configurations of the Virtual Connect by making the following request i.e.
curl --request GET \
--url 'https://{{IX-API url}}/ixapi/v2/network-service-configs?network_service={{Virtual Connect Id}} ' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
The response shall return an http response code of 200 OK with the following response body.
{
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 1215,
"vlan_ethertype": "0x8100"
},
"role_assignments": [
"87b9d494-88d1-4626-f6ee-08db1b4907a6"
],
"state": "production",
"billing_account": "A0087264",
"capacity": 100,
"connection": "CANL-051335",
"consuming_account": "A0087264",
"contract_ref": "NA",
"external_ref": "4364",
"id": "114e59b6-337c-44d3-9a4f-49ee4c9d6bc3",
"managing_account": "A0087264",
"network_service": "VLC00050171",
"purchase_order": "6434664",
"type": "p2p_vc"
}
Note, you can only edit your side of the Virtual Connect
Step 3: Change Dot1q VLAN Id
Make the following request to change the Dot1q VLAN Id on the Virtual Connect:
curl --request PATCH \
--url https://{{IX-API url}}/ixapi/v2/network-service-configs/{{Virtual Connect Id}} \
--header 'Authorization: Bearer {{YOUR TOKEN}}' \
--data '{
"type": "p2p_vc",
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 301
}
}'
An http 200 OK response shall be returned with the following response body
{
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 301,
"vlan_ethertype": "0x8100"
},
"role_assignments": [
"87b9d494-88d1-4626-f6ee-08db1b4907a6"
],
"state": "production_change_pending",
"billing_account": "A0087264",
"capacity": 100,
"connection": "CANL-051335",
"consuming_account": "A0087264",
"contract_ref": "NA",
"external_ref": "4364",
"id": "114e59b6-337c-44d3-9a4f-49ee4c9d6bc3",
"managing_account": "A0087264",
"network_service": "VLC00050171",
"purchase_order": "6434664",
"type": "p2p_vc"
}
Note the response includes the new "vlan" Id and "state" of the resource is "production_change_pending", meaning the change is accepted and is being provisioned on the network.
Once the change has completed, the "state" of the resource shall be returned as "production".
When the resources is in "state" of "production_change_pending" you can submit more changes and the final one in a sequence of one or more shall be the last one applied.
Step 4: Change Dot1q to QinQ
Make the following request to change the Dot1q VLAN Id on the Virtual Connect A or B side:
curl --request PATCH \
--url https://{{IX-API url}}/ixapi/v2/network-service-configs/{{Virtual Connect Id}} \
--header 'Authorization: Bearer {{YOUR TOKEN}}' \
--data '{
"type": "p2p_vc",
"vlan_config": {
"vlan_type": "qinq",
"inner_vlan": "33"
}
}'
Note, where an "outer_vlan" value is not included the existing "vlan" value shall be preserved.
An http 200 OK response shall be returned with the following response body
{
"vlan_config": {
"vlan_type": "qinq",
"outer_vlan": 301,
"outer_vlan_ethertype": "0x8100",
"inner_vlan": 33
},
"role_assignments": [
"87b9d494-88d1-4626-f6ee-08db1b4907a6"
],
"state": "production_change_pending",
"billing_account": "A0087264",
"capacity": 100,
"connection": "CANL-051335",
"consuming_account": "A0087264",
"contract_ref": "NA",
"external_ref": "4364",
"id": "114e59b6-337c-44d3-9a4f-49ee4c9d6bc3",
"managing_account": "A0087264",
"network_service": "VLC00050171",
"purchase_order": "6434664",
"type": "p2p_vc"
}
Note the response includes the preserved "outer_vlan" and "state" of the resource is "production_change_pending", meaning the change is accepted and is being provisioned on the network.
Once the change has completed, the "state" of the resource shall be returned as "production".
When the resources is in "state" of "production_change_pending" you can submit more changes and the final one in a sequence of one or more shall be the last one applied.
Step 5: Change QinQ outer_vlan and/or inner_vlan
Make the following request to change the QinQ "outer_vlan" and/or 'inner_vlan" on the Virtual Connect A or B side:
curl --request PATCH \
--url https://{{IX-API url}}/ixapi/v2/network-service-configs/{{Virtual Connect Id}} \
--header 'Authorization: Bearer {{YOUR TOKEN}}' \
--data '{
"type": "cloud_vc",
"vlan_config": {
"vlan_type": 'qinq',
"outer_vlan": "909",
"inner_vlan": "808"
}
}'
An http 200 OK response shall be returned with the following response body
{
"vlan_config": {
"vlan_type": "qinq",
"outer_vlan": 909,
"outer_vlan_ethertype": "0x8100",
"inner_vlan": 808
},
"role_assignments": [
"87b9d494-88d1-4626-f6ee-08db1b4907a6"
],
"state": "production_change_pending",
"billing_account": "A0087264",
"capacity": 100,
"connection": "CANL-051335",
"consuming_account": "A0087264",
"contract_ref": "NA",
"external_ref": "4364",
"id": "114e59b6-337c-44d3-9a4f-49ee4c9d6bc3",
"managing_account": "A0087264",
"network_service": "VLC00050171",
"purchase_order": "6434664",
"type": "p2p_vc"
}
Note the "state" of the resource is "production_change_pending", meaning the change is accepted and is being provisioned on the network.
Once the change has completed, the "state" of the resource shall be returned as "production".
When the resources is in "state" of "production_change_pending" you can submit more changes and the final one in a sequence of one or more shall be the last one applied.
Step 6: Change QinQ to dot1q
Make the following request to change QinQ vlan type to Dot1q.
curl --request PATCH \
--url https://{{IX-API url}}/ixapi/v2/network-service-configs/{{Virtual Connect Id}} \
--header 'Authorization: Bearer {{YOUR TOKEN}}' \
--data '{
"type": "cloud_vc",
"vlan_config": {
"vlan_type": 'dot1q'
}
}'
An http 200 OK response shall be returned with the following response body
{
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 909,
"vlan_ethertype": "0x8100"
},
"role_assignments": [
"87b9d494-88d1-4626-f6ee-08db1b4907a6"
],
"state": "production_change_pending",
"billing_account": "A0087264",
"capacity": 100,
"connection": "CANL-051335",
"consuming_account": "A0087264",
"contract_ref": "NA",
"external_ref": "4364",
"id": "114e59b6-337c-44d3-9a4f-49ee4c9d6bc3",
"managing_account": "A0087264",
"network_service": "VLC00050171",
"purchase_order": "6434664",
"type": "p2p_vc"
}
Note
the "outer_vlan" value is preserved as the "inner_vlan" value. Where the vlan value is not explicitly set the existing value shall persist.
the "state" of the resource is "production_change_pending", meaning the change is accepted and is being provisioned on the network.
Once the change has completed, the "state" of the resource shall be returned as "production".
When the resources is in "state" of "production_change_pending" you can submit more changes and the final one in a sequence of one or more shall be the last one applied.
3. Edit Bandwidth or metadata of a Virtual Connect
As well as bandwidth, the following metadata that can be changed:
"external_ref": "Test External Ref",
"purchase_order": "Test PO Number",
"contract_ref": "Test Contract Ref"
Step 1: Use client credentials to generate an access token
Make the following request to generate an access token:
curl --location --request POST 'https://{{login-url}}/connect/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'client_secret=<client_secret>'
The response is a http 200 OK with response body containing the access token.
{
"access_token": "{YOUR_TOKEN}",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "resource.api resource.ixapi resource.productcatalogapi"
}
The access token in the response shall be used in all subsequent requests.
Authentication
When you make an API call, you need to use an “Authorization” HTTP header to provide your API key, with a “Bearer” prefix. For example:
Authorization: Bearer {YOUR_TOKEN}
Step 2: Read the Virtual Connnet
Use the Virtual Connect Id to read the Virtual Connect by making the following request to see the current bandwidth.
curl --request GET \
--url 'https://{{IX-API url}}/ixapi/v2/network-services/{{Virtual Connect Id}} ' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
The response shall return an http response code of 200 OK with the following response body.
{
"id": "VLC00050171",
"state": "production",
"nsc_required_contact_roles": [],
"capacity": 100,
"status": [
{
"severity": 6,
"tag": "requested",
"message": "Eline service was requested",
"attrs": {
"request_date": "2023-03-28T00:00:00"
},
"timestamp": "2023-03-28T11:58:24"
}
],
"consuming_account": "A0087264",
"external_ref": "4364",
"managing_account": "A0087264",
"product_offering": "503121.AMS.AMS",
"type": "p2p_vc",
"billing_account": "A0087264",
"contract_ref": "TEST Ref",
"joining_member_account": "A0087264",
"purchase_order": "6434664"
}
The above response body shows that this Virtual Connect uses a "product_offering" whose value can de-referenced by using the following request
curl --request GET \
--url https://{{IX-API url}}/ixapi/v2/product-offerings/503121.AMS.AMS \
--header 'Authorization: Bearer {YOUR TOKEN}'
The following response body is returned for the product offering with an HTTP 200 OK response:
{
"id": "503121.AMS.AMS",
"physical_port_speed": 100,
"bandwidth_max": 100,
"bandwidth_min": 100,
"resource_type": "network_service",
"provider_vlans": "single",
"display_name": "Amsterdam-Amsterdam-Cloud Connect : Virtual Connect Service - 100Mb",
"downgrade_allowed": true,
"handover_metro_area": "AMS",
"handover_metro_area_network": "AMS",
"name": "Amsterdam-Amsterdam-Cloud Connect : Virtual Connect Service - 100Mb",
"service_provider": "Interxion",
"type": "p2p_vc",
"upgrade_allowed": true,
"service_metro_area": "AMS",
"service_metro_area_network": "AMS"
}
This shows the product-offering of the Virtual Connect is 100 Mb.
To change bandwidth a new product offering has to be selected and submitted.
Step 3: Change Bandwidth of Virtual Connect
Use the following PATCH request to change the bandwidth of a Virtual Connect and it's metadata property values for external_ref, purchase_order and contract_ref.
curl --request PATCH \
--url https://{{IX-API url}}/v2/network-services/{{Virtual Connect Id}} \
--header 'Authorization: Bearer {YOUR_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
"type": "p2p_vc",
"product_offering": "503122.AMS.AMS",
"external_ref": "Test External Ref",
"purchase_order": "Test PO Number",
"contract_ref": "Test Contract Ref" }'
The response to the above request is an http 200Ok with the following response body:
{
"id": "VLC00050171",
"state": "production_change_pending",
"nsc_required_contact_roles": [],
"capacity": 100,
"status": [
{
"severity": 6,
"tag": "requested",
"message": "Eline service was requested",
"attrs": {
"request_date": "2023-03-28T00:00:00"
},
"timestamp": "2023-03-28T11:58:24"
}
],
"consuming_account": "A0087264",
"external_ref": "4364",
"managing_account": "A0087264",
"product_offering": "503122.AMS.AMS",
"type": "p2p_vc",
"billing_account": "A0087264",
"contract_ref": "TEST Ref",
"joining_member_account": "A0087264",
"purchase_order": "6434664"
}
The change to bandwidth and metadata has been accepted and the state of the resource is "production_change_pending". The above request can support any combination of bandwidth and metadata.
The resource should be polled and when the state changes to "Production" the change is applied.
There is no restriction on the number of changes. However, if a change is being processed and a new change is submitted, the current will be parked and the latest change processed and applied.
Step 4: Read the Virtual Connect state to determine if the changes have been applied
Make the following request to review the state of the Virtual Connect.
curl --request GET \
--url 'https://{{IX-API url}}/ixapi/v2/network-services/{{Virtual Connect Id}} ' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
The response shall return an http response code of 200 OK with the following response body.
{
"id": "VLC00050171",
"state": "production",
"nsc_required_contact_roles": [],
"capacity": 100,
"status": [
{
"severity": 6,
"tag": "requested",
"message": "Eline service was requested",
"attrs": {
"request_date": "2023-03-28T00:00:00"
},
"timestamp": "2023-03-28T11:58:24"
}
],
"consuming_account": "A0087264",
"external_ref": "4364",
"managing_account": "A0087264",
"product_offering": "503122.AMS.AMS",
"type": "p2p_vc",
"billing_account": "A0087264",
"contract_ref": "TEST Ref",
"joining_member_account": "A0087264",
"purchase_order": "6434664"
}
When the state changes from "production_change_pending" to "production" the change requested has been completed.