Using IX-API for point to point virtual circuit (Virtual Connect)
Connect / Disconnect using Joining member account workflow
This page describes how to use the IX-API to provision and deprovision a Virtual Connect (point to point virtual circuit) using the joining member account provision workflow. Two provisioning workflows are available for Virtual Connect.
Joining member account.
This is the IX-API default. The A side creates a point to point virtual circuit, adds a B side as an explicit joining member account for that virtual circuit, and chooses their own cloud access port and VLAN setting. The B side is able to join the point to point virtual circuit as they are attributed as a joining member account and they choose their cloud access port / VLAN settings to complete their side of the virtual circuit.
Service key
This is an Interxion extension to the core IX-API. An inviting party provides a subscribing party a service key for a cloud access port. The subscribing party uses the service key to create a point to point virtual circuit and chooses their cloud access port / VLAN setting. The inviting party is able to see the virtual circuit as their service key is used and they choose their cloud access port (has to match that referenced by the service key) / VLAN setting to complete their side of the virtual circuit.
This page describes the joining member account workflow.
1. Request Client Credentials
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. Download Postman Collection
This Postman Collection provides examples of all the API calls you need to make to connect / disconnect a point to point virtual circuit (virtual connect)
Joining Member Postman Collection
3. Provision a Virtual Connect (point to point virtual circuit) using joining member account provisioning workflow
Please refer to the V2 IX-API open api specification here https://docs-staging.ix-api.net (latest) and https://docs.ix-api.net (officially published).
This specification covers the joining member account provisioning workflow for point to point virtual circuit.
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"
}
Different tokens may be needed depending on the permissions required for the A or B side account used in which case the token should be retrieved as indicated here.
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: Choose Product Offerings
Make the following request to retrieve all product-offerings you have permission/authorisation for. This request uses the client credentials access token.
curl --location --request GET 'https://{{ix-api-url}}/ixapi/v2/product-offerings' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
The response is a http 200 OK with response body containing product-offerings
[
{
"id": "503128.LON.AMS",
"physical_port_speed": 5000,
"bandwidth_max": 5000,
"bandwidth_min": 5000,
"resource_type": "network_service",
"provider_vlans": "single",
"display_name": "London-Amsterdam-Cloud Connect : Virtual Connect Service - 5Gb",
"downgrade_allowed": false,
"handover_metro_area": "LON",
"handover_metro_area_network": "LON",
"name": "London-Amsterdam-Cloud Connect : Virtual Connect Service - 5Gb",
"service_provider": "Interxion",
"type": "p2p_vc",
"upgrade_allowed": false,
"service_metro_area": "AMS",
"service_metro_area_network": "AMS"
},
...
]
In the response the relevant product offerings have "type": "p2p_vc".
Step 3: Choose Cloud Access Ports
Make the following request to retrieve all cloud access ports you have permissions for.
curl --location --request GET 'https://{{ix-api-url}}/ixapi/v2/product-offerings' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
The response is a http 200 OK with response body containing cloud access ports.
[
{
"id": "CANL-051075",
"mode": "standalone",
"outer_vlan_ethertypes": [
"0x8100"
],
"state": "production",
"vlan_types": [
"dot1q",
"qinq"
],
"billing_account": "A0087264",
"capacity_allocated": 1400,
"capacity_allocation_limit": 10000,
"consuming_account": "A0087264",
"contract_ref": null,
"external_ref": null,
"managing_account": "A0087264",
"name": "CANL-051075",
"pop": "AMS5-B",
"port_quantity": 1,
"port_reservations": [
"CANL-051075"
],
"ports": [
"CANL-051075"
],
"product_offering": "503235.AMS5-B.E",
"role_assignments": [],
"speed": 10000,
"status": [],
"subscriber_side_demarcs": []
} ...
]
The selected cloud access ports must have "state": "production" and should match the location for the product-offerings.
Step 4: Create point to point virtual circuit (Virtual Connect)
Make the following request to request a point to point virtual circuit.
The request uses:
· client credentials access token
· "managing_account" a mandatory property which is the account who will manage the the Virtual Connect.
· "consuming_account" a mandatory property which is the account who will consume the Virtual Connect and can be the same as the "managing_account"
· "external_reference" an optional property which is a free text value for the client to provide a customer reference value
· "purchase_order" an optional property which is a free text value for the client to provide a purchase order number value
· "contract_ref" an optional property which is free text value for the client to provide a contract reference value
· "billing_account" a mandatory property which is the account who will be billed for the Virtual Connect.
· "product_offering" a mandatory property which is the id of the product-offering selected in earlier steps
"joining_member_account" a mandatory property which is the account id of the B side
curl --location --request POST 'https://{{ix-api-url}}/ixapi/v2/network-services' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZ...' \
--header 'Content-Type: text/plain' \
--data-raw '{
"type": "p2p_vc",
"managing_account": "A0073476",
"consuming_account": "A0073476",
"external_ref": "4364",
"purchase_order": "6434664",
"contract_ref": "TEST Ref",
"product_offering": "inxn-virtual-connect",
"billing_account": "A0073476",
"capacity": 100,
"joining_member_account": "A0087264"
}'This will return a http 201 created response with response body as follows:
{
"id": "VLC00050250",
"state": "requested",
"nsc_required_contact_roles": [
"4699403d-b264-4a47-9bbb-2c956dcd1a12",
"9a442fef-ff8f-4c2e-93e5-46425c00fd4b"
],
"contract_ref": "TEST Ref",
"provider_ref": "",
"capacity": 100,
"status": [
{
"severity": 6,
"tag": "requested",
"message": "Eline service was requested",
"attrs": {
"request_date": "2022-03-22T00:00:00"
},
"timestamp": "2022-03-22T19:06:28"
}
],
"consuming_account": "A0073476",
"external_ref": "4364",
"managing_account": "A0073476",
"product_offering": "inxn-virtual-connect",
"type": "p2p_vc",
"billing_account": "A0073476",
"joining_member_account": "A0087264",
"purchase_order": "6434664"
}
The property in the response "nsc_required_contact_roles" shall provide identifiers for the role assignments that must be provided for the A and B side of the point to point virtual circuit. This property may return an empty array if no contact roles are required.
Step 5: Read roles to determine which role-assignments are needed
If the response in Step 4 returns identifiers for "nsc_required_contact_roles" then this query shall provide the roles that must be provided when the network-service-configs are requested in later steps.
Make the following request to retrieve all roles you have permission/authorisation for. This request uses the client credentials access token.
curl --location --request GET 'https://{{ix-api-url}}/ixapi/v2/roles' \
--header 'Authorization: Bearer {YOUR_TOKEN}'The response is a http 200 OK with response body containing roles
[
{
"id": "4699403d-b264-4a47-9bbb-2c956dcd1a12",
"name": "Implementation",
"required_fields": [
"name",
"email",
"telephone"
] ...
},
...
]
Existing role-assignments can be used but if needed new ones can be created whereby a contact is created first and assigned to a role using role-assignments.
Adding contacts
A Contact is assigned a Role via Role-Assignments. If a role assignment is needed as per property "nsc_required_contact_roles" then a Contact can be created and assigned a role.
Make the following request to create a contact. The request uses the client credentials access token.
curl --location --request POST 'https://{{ix-api-url}}/ixapi/v2/contacts' \
--header 'Authorization: Bearer {YOUR_TOKEN}' \
--data-raw '{
"managing_account": "A0087999",
"consuming_account": "A0087999",
"name": "Panda Lion",
"email": "dummy2@dummy.com",
"telephone": "+2314412333223"
}'The response is a http 200 OK with response body containing contact:
{
"id": "0092d959-6f47-478e-d2e2-08d9b8c2e666",
"consuming_account": "A0087999",
"email": "dummy2@dummy.com",
"external_ref": null,
"managing_account": "A0087999",
"name": "Panda Lion",
"telephone": "+2314412333223"
}A single contact can be assigned to multiple role assignments. Please create as many Contacts as needed for the role assignments.
Adding role assignments - associating a contact to a role
To assign a Role to a Contact the following step is followed to create a Role Assignment.
Make the following request to create a role assignment. The request uses the client credentials access token.
curl --location --request POST 'https://{{ix-api-url}}/ixapi/v2/role-assignments' \
--header 'Authorization: Bearer {YOUR_TOKEN}' \
--data-raw '{
"role": "4699403D-B264-4A47-9BBB-2C956DCD1A12",
"contact": "7b1bf663-e8e5-4493-29f5-08d9ba38d667",
}'
The response is an http 201 Created with response body containing role assignment:
{
"id": "15c2001a-9bc8-4236-c560-08d9ba38e2ec",
"contact": "7b1bf663-e8e5-4493-29f5-08d9ba38d667",
"role": "4699403d-b264-4a47-9bbb-2c956dcd1a12"
}Step 6: A side cloud access port and VLAN
Make the following request to add the A side of the point to point virtual circuit, specifically which cloud access port to use and the VLAN setting. If the "nsc_required_contact_roles" in step 4 listed contacts for the network-service-configs then these must be provided in this request payload through the property "role-assignments".
curl --location --request POST 'https://{{ix-api-url}}/ixapi/v2/network-service-configs' \
--header 'Authorization: Bearer {YOUR_TOKEN}' \
--data-raw '{
"type": "p2p_vc",
"managing_account": "A0073476",
"consuming_account": "A0073476",
"external_ref": "4364",
"network_service": "VLC00050250",
"purchase_order": "6434664",
"contract_ref": "NA",
"billing_account": "A0073476",
"role_assignments": [
"3f403181-2dc0-42b2-08dc-08d99f835763",
"c23c1a9c-5813-4fe1-08dd-08d99f835763"
],
"connection": "CAUK-051612",
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 2203,
"vlan_ethertype": "0x8100"
}'
The response is a http 201 created. The "state": "allocated" indicates the resource is reserved and awaits the B side.
{
"id": "a67be874-ee32-4e03-9d37-f3cb91bb43b3",
"type": "p2p_vc",
"network_service": "VLC00050250",
"managing_account": "A0073476",
"consuming_account": "A0073476",
"external_ref": "4364",
"purchase_order": "6434664",
"contract_ref": "NA",
"billing_account": "A0073476",
"role_assignments": [
"3f403181-2dc0-42b2-08dc-08d99f835763",
"c23c1a9c-5813-4fe1-08dd-08d99f835763"
],
"connection": "CAUK-051612",
"network_feature_configs": [],
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 2203,
"vlan_ethertype": "0x8100"
},
"state": "allocated",
"status": []
}
Step 7: B side cloud access port and VLAN
The B side may require B side client credentials to be used to retrieve an access token authorised to complete actions as the B side.
Make the following request to add the B side of the point to point virtual circuit, specifically which cloud access port to use and the VLAN setting. If the "nsc_required_contact_roles" in step 4 listed contacts for the network-service-configs then these must be provided in this request payload through the property "role-assignments".
curl --location --request POST 'https://{{ix-api-url}}/ixapi/v2/network-service-configs' \
--header 'Authorization: Bearer {YOUR_TOKEN}' \
--data-raw '{
"type": "p2p_vc",
"managing_account": "A0087264",
"consuming_account": "A0087264",
"external_ref": "4364",
"network_service": "VLC00050250",
"purchase_order": "6434664",
"contract_ref": "NA",
"billing_account": "A0087264",
"role_assignments": [
"eeb1b37d-375d-4331-728f-08da0c39180b",
"2eb856a2-ba09-4a04-7290-08da0c39180b"
],
"connection": "CANL-051305",
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 2204,
"vlan_ethertype": "0x8100"
}'
The response is a http 201 created. The "state": "allocated" indicates the resource is reserved and this triggers provisioning.
{
"id": "82c693ec-2bed-4503-b712-a8e7ddf87e1e",
"type": "p2p_vc",
"network_service": "VLC00050250",
"managing_account": "A0087264",
"consuming_account": "A0087264",
"external_ref": "4364",
"purchase_order": "6434664",
"contract_ref": "NA",
"billing_account": "A0087264",
"role_assignments": [
"eeb1b37d-375d-4331-728f-08da0c39180b",
"2eb856a2-ba09-4a04-7290-08da0c39180b"
],
"connection": "CANL-051305",
"network_feature_configs": [],
"vlan_config": {
"vlan_type": "dot1q",
"vlan": 2204,
"vlan_ethertype": "0x8100"
},
"state": "allocated",
"status": []
}
Step 8: Read point to point virtual circuit to check it is provisioned
Make the following request to check the state of the point to point virtual circuit. The state shall change to "Production" when the installation completes.
curl --location --request GET 'https://{{ix-api-url}}/ixapi/v2/network-services/<id>' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
This shall result in an http 200 OK response with response body as follows:
{
"id": "VLC00050250",
"state": "production",
"nsc_required_contact_roles": [
"4699403d-b264-4a47-9bbb-2c956dcd1a12",
"9a442fef-ff8f-4c2e-93e5-46425c00fd4b"
],
"contract_ref": "TEST Ref",
"capacity": 100,
"status": [
{
"severity": 6,
"tag": "requested",
"message": "Eline service was requested",
"attrs": {
"request_date": "2022-03-22T00:00:00"
},
"timestamp": "2022-03-22T20:36:01"
}
],
"consuming_account": "A0073476",
"external_ref": "4364",
"managing_account": "A0073476",
"product_offering": "inxn-virtual-connect",
"type": "p2p_vc",
"billing_account": "A0073476",
"joining_member_account": "A0087264",
"purchase_order": "6434664"
}
Step 9: Deprovision point to point virtual circuit
Make this request to request deprovision the point to point virtual circuit.
curl --location --request DELETE 'https://{{ix-api-url}}/ixapi/V2/network-services/VLC00050250' \
--header 'Authorization: Bearer {YOUR_TOKEN}'The response is an http 202 Accepted with response body
{
"id": "VLC00050250",
"state": "decommission_requested",
"nsc_required_contact_roles": [],
"contract_ref": "TEST Ref",
"capacity": 100,
"status": [
{
"severity": 6,
"tag": "requested",
"message": "Eline service was requested",
"attrs": {
"request_date": "2022-03-22T00:00:00"
},
"timestamp": "2022-03-22T20:35:43"
}
],
"consuming_account": "A0073476",
"external_ref": "4364",
"managing_account": "A0073476",
"product_offering": "inxn-virtual-connect",
"type": "p2p_vc",
"billing_account": "A0073476",
"charged_until": "2022-03-22",
"decommission_at": "2022-03-22",
"joining_member_account": "A0087264",
"purchase_order": "6434664"
}
The "charged_until" is the date on which billing will end and the "decommission_at" is the date on which the point to point virtual circuit shall be de-provisioned.
Step 10 Check the disconnect is completed
To check the disconnect has completed, read the cloud access port using the request here:
curl --location --request GET 'https://{{ix-api-url}}/ixapi/v2/network-services/<id>' \
--header 'Authorization: Bearer {YOUR_TOKEN}'
The response shall be the same as in step 9 above until the point to point virtual circuit is deprovisioned when instead an http 404 Not Found shall be returned.