SDN API

How to get access to this API?

If you are a Colt customer then please contact your Account Executive.

What is the onboarding process?

Your Account Executive will request the logins for the sandbox account. AE will share the details with you.

The sandbox environment has production like features and you are free to test any use case using the APIs. Our devops team will support you during this period.

Once you are ready with API development and want to move to production , the Account executive has to raise separate registration request that creates Colt online logins and On demand platform credentials. 

How to get support for this API?

You can use the support option available in On-demand portal   for post-production support.

Not a customer yet?

Contact our Sales Team  

How to Try the API?

To try the API and different operations please use On demand API Documentation  

Colt On Demand Solutions

Colt On Demand Service is the solution for your business sites to cloud computing, disaster recovery, business continuity planning, content delivery, applications and host of other remotely-based IT services.

OnDemand platform provide below main product offerings.

• Ethernet on Demand - On Demand connectivity to private enterprise locations Extends On Demand offering to 25,000+ enterprise buildings across Europe and APAC Supports data centre to Enterprise and Enterprise to Enterprise connectivity Supports on-net and near-net locations. On Demand connectivity between data centres.800+ Data Centres with shared equipment areas in Europe, APAC and the US 200+ data centres that support real time delivery

• Cloud On Demand - connectivity into the cloud. Connectivity from data centre & Enterprise buildings into the public cloud Both API enabled hosted connectivity and dedicated port connectivity to the cloud Available for Microsoft Azure, ExpressRoute, Amazon Web Services Direct Connect, Google Cloud Partner Interconnect, IBM Direct Link and Oracle FastConnect

• IP Access on Demand - On Demand internet connectivity. Connectivity from data entre & Enterprise buildings into the public internet Customers benefit from Colt’s carrier grade internet access service with additional On Demand features such as flexible commercials and real time upgrades Initially only available in Europe, up to 1Gbps

• Cross-connects. In Datacentres / Carrier Hotels, Colt delivers the ports to a shared location CEA / MMR. It is the customer responsibility to order a cross-connect from the CEA/MMR to their own equipment. This can be ordered directly by the customer with the data centre provider or via Colt at selected locations. Only available for optical ports.

Product Structure

Colt On Demand is based on components which can be used to build end to end services. These components are re-usable and distinct, with attributes specific to each component such as bandwidth and contract term. The components available are:

1. Ethernet ports
2. Ethernet connections
3. Cloud ports
4. Cloud connections
5. IP Access connections
6. Cross connect

The Use-cases section describes how to achieve these functionalities using different APIs.By combining 2 or more of the above components any network topology can be created, from a simple point to point ethernet link or internet access at one location to complex mesh network topologies. For some examples on how to provision the most common network service topologies please refer to the ‘End to end use cases’ section.

API Security

All the Colt SDN APIs are protected by SSL/TLS encryption, so when you call them you should ensure your client code is using this mechanism. The APIs need secured token which has to be provided with every request to access them.

Generic Response Code

The following table shows how and when response codes must be used within the API.

Success

Errors

Versioning

We use the following rules when versioning:

1. Most of the existing APIs use version as an optional parameter.
2. When updating an existing endpoint, we add a new endpoint with a /v2/... (or /v3, etc) prefix. We do this under the following circumstances:
   When a new mandatory attribute is added or an existing optional attribute is made mandatory. When an existing attribute is removed (optional or mandatory).
   The original endpoint and schema object remain unchanged. We will support up to 3 versions of an endpoint and we will supply 6 months’ notice to all registered users before we retire an endpoint version.

Use-cases

This section describes the APIs and the endpoints that are used in different process steps as mentioned in the introduction section.

End points

Use new API v2/port/services to create,modify,delete and retrieve Ethernet port

Ethernet ports

Under the On Demand model, ports are a separate component - unlike the traditional data networking model where ports are an integral part of a circuit connection. All On Demand ports are capable of supporting multiple service types, using VLAN segregation. Example use cases include:

• Multicloud – multiple cloud connections terminating on the same physical On Demand port at the customer site
• NNI for Ethernet Virtual Private Line – multiple Ethernet connections aggregated on the same physical port for service provider handoff
• Enterprise multi service – internet access, data centre connections and multiple cloud connections to support typical enterprise WAN services.
  Colt supports a full range of physical 1Gbps, 10Gbps & 100Gbps port specifications. Please note diversity and resilience options for Ethernet Ports are not available via the On Demand platform.
  This section describes the APIs used to retrieve list and associated data, create, modify and delete an Ethernet port.

Add an Ethernet Port

To add an Ethernet port use following sets of APIs.
Step1. To search for a building from customer address book Use GET api/locations/ or to search from global database use GET /api/global_directory/address which uses city, country, building name, street name, post code or google place identifier (this is retrieved from google maps for more information refer https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder) as optional query parameter. Count is set to 100 to retrieve first 100 records

Step2. Existing site:
Once you identified the building where a port has to be installed next search for the site. Use GET api/building/{building_id}/site to retrieve the site details along with capacity available at the site. This results in retrieving Logical port speed , port interface and connector.

Step3. Retrieve price for selected product using GET api/prices?service_type={service_type}&building_id={building identifier}&product_id= {product_id} where service_type is ETHERNETPORTand building identifier or location identifier is retrieved from Step1 and product_id from Step2

Step4. Existing capacity
Finally use POST /api/v2/port/services with payload

{
  "price_id": ,
  "site_id": "",
  "port_name": ""
}

where price_id is retrieved from above Step3, location_id from /global_directory and port_name is given name of the new port. The API returns the request and service identifier.

New capacity
If the capacity is not available, first create a temporary site in the given building by using POST /api/locations using the payload

{
 "building_id": "",
 "site_floor": "",
 "site_room_name": ""
}

Use GET api/products?service_type=ETHERNETPORT&location_id={location_id} to retrieve the products that are available at that building where the location_id is the the temporary site id

Next retrieve price for selected product using GET api/prices?service_type={service_type}&building_id={building identifier}&product_id= {product_id} where service_type is ETHERNETPORT and building identifier or location identifier is temporary site created earlier

Next create the port using the same endpoint /api/v2/port/services used in existing capacity with payload given below

{
  "site_access_price_id": ,
  "name": "",
  "price_id": ,
  "site_access_details": {
    "access_out_of_hours": true,
    "notice_required_days": "0",
    "site_contact": {
      "email": "",
      "name": "",
      "phone": ""
    },
    "technical_contact": {
      "email": "",
      "name": "",
      "phone": ""
    },
    "technical_contact_company": "string",
    "user_contact": {
      "email": "",
      "name": "",
      "phone": ""
    }
  },
  "site_id": ""
}

where site_access_price_id can be retrived using GET /api/prices?service_type=SITEPORT&location_id={location_id}, price_id is the price associated with the ethernet port and site_access_details are details assoicated with the site.

Refer a flowchart below for the process steps.

Rename an Ethernet port

Use PATCH /api/v2/port/services/{port_id} to Rename the port. Provide new port_name as payload

Delete an Ethernet Port

Use DELETE /api/v2/port/services/{port_id} to Delete the port.

List Ethernet ports

Use GET /api/v2/port/services to retrieve all the ports

Retrieve a single Ethernet Port information

Use GET /api/v2/port/services/{port_id} to retrieve data of an individual port. Products, prices, address details are the key set of information retrieved from the API.

Download Letter of Authority

Use POST /api/v2/port/services/{port_id}/loa endpoint and provide issued_to as payload to get the LOA

Find related requests

Use GET /api/v2/port/requests/

Find related connections

Retrieve service_id using GET /api/v2/port/services/{port_id} endpoint Next use /api/v2/connection/services and check if the service_id is associated with component_connections as from_port_id or to_port_id

Find related cross connection

Use Get /api/cross_connect and search for associated_port_id in the response object as the given port

Cloud Ports

Colt has enabled automated service orchestration with multiple cloud service providers (CSP) such as MS Azure and AWS for real-time connectivity to the cloud using existing Colt-CSP interconnects. Customers can connect from all On Demand enabled locations (including all data centres and enterprise locations) to the public cloud by reserving a Cloud port against the desired cloud provider and creating a Cloud connection to it from any existing Ethernet port. Although the process to create a cloud port is slightly different for each cloud provider, the overall On Demand cloud service model is always the same with two cloud-specific service components: a cloud port and a cloud connection to it from a standard port. Cloud connections terminate on standard ports which can be in either data centres or enterprise locations. Cloud port – to – cloud port connections are not currently supported. Customers who wish to flex the bandwidth on their cloud circuit connections are advised to over-size the cloud port to enable bandwidth to be flexed up to this limit. Below section describes the different APIs use operate on cloud ports.

MS Azure ExpressRoute

Add cloud port

To order an Azure port follow below steps-
Step 1. Go to Azure portal and create an ExpressRoute service selecting ‘Colt’ as the provider. Get a service key (UUID)
Step 2. GET api/prices?service_type=CLOUDPORT&service= AZURE_EXPRESS to retrieve all the prices for cloud provider
Step 3. Call POST api/ports with below payload

{
  "port_name": "Azure port",
  "price_id": <price_id>,
  "cloud_provider": "AZURE_EXPRESS",
  "azure_service_key": "< azure_service_key >"
}

Where port_name is given name, Price_id is retrieved from first call ,azure_service_key provided by cloud provider in Step 1.

Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/ports/{port_id} to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports data and search for cloud_provider= "AZURE_EXPRESS” in the results

Retrieve a single Cloud Port information

Use GET /api/ports/{port_id}

Find related requests

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= "AZURE_EXPRESS” in the results

AWS DirectConnect Dedicated Cloud Port

Dedicated cloud ports can support multiple EVPL services with different VLANs.

Add Cloud Port

To order an AWS direct connect Dedicated port follow below steps
Step 1. Log into AWS console. Select Correct region and direct connect PoP. Download Letter of Authority.
Step 2. Use GET api/cloudsites to retrieve AWS regions, interconnects data which has site_type information
Step 3. Next use GET api/prices?service_type=CLOUDPORT&service= AWS_DEDICATED&site_type={site_type} to retrieve all the prices for cloud provider
Step 4. Call POST api/ports with below payload

{
  "port_name": "< port_name >",
  "price_id": "<price_id>",
  "cloud_provider": "AWS_DEDICATED",
  "aws_region": "<aws_region>",
  "building_id": "<building_id>",
  "loa": loa.pdf
}

where port_name is given port name price_id is retrieved basis site_type and service from the prices api aws_region is region created by AWS basis the data centre in a geography e.g. Europe central1 retrieved from the /cloudsites endpoint , building_id is retrieved from the /cloudsites endpoint and loa is Letter of authority retrieved from Step 1. Note this port is not created on demand and takes time

Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/ports/{port_id} to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports and search for cloud_provider= " AWS_DEDICATED” in the results

Retrieve Cloud Port information

Use GET /api/ports/{port_id}

Find related requests

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= " AWS_DEDICATED” in the results

AWS DirectConnect Hosted Cloud Port

Hosted cloud ports can only have 1 connection at a time and no VLAN config can be done on the cloud port end.

Add Cloud Port

Step 1.
Log into AWS console. Select Correct region and direct connect PoP. Generate the AWS Account number.
Step 2.
Use GET api/cloudsites to retrieve AWS regions, interconnects data which has site_type , region and building_id information Step 3.
Next use GET /api/prices?service_type=CLOUDPORT&service=AWS_HOSTED&region={region_id}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth Step 4.
Call POSTapi/ports with below payload

{
  "port_name": "< port_name >",
  "price_id": "<price_id>",
  "cloud_provider": "AWS_HOSTED",
  "aws_account_no": "<aws_account_no>",
  "building_id": "<building_id>",
  "aws_region": ",<aws_region>"
}

where port_name is given port name price_id is retrieved from the prices api aws_account_no is provided by AWS in Step 1. aws_region Regions created by AWS basis the data centre in a geography e.g. Europe central 1 building_id is retrieved from the api/cloudsites endpoint.
Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/ports/{port_id}to Rename the port. Use payload name= where name= updated name and port_id is the port identifier

Delete Cloud Port

Use DELETE /api/ports/{port_id} to Delete the port where port_id is the port identifier

List Cloud Ports

Use GET api/ports to retrieve all the ports and search for cloud_provider= " AWS_HOSTED” in the result

Retrieve a single Cloud Port information

Use GET api/ports/{port_id} where port_id is the identifier for the port

Find related requests

Use GET /api/requests and search for resource as “PORT” for given port_id and cloud_provider= " AWS_HOSTED” in the result

Google Cloud Partner Interconnect

Add Cloud Port

To order Google cloud partner interconnect port follow same steps
Step 1. Login to Google Cloud Platform portal. Choose colt as provider. Generate pairing key. Use following steps to create Google cloud port. If the pairing key is partially activated after creating a port using the API, key has to be activated again by login to google platform
Step 2. Use GET api/cloudsites to retrieve Google regions, interconnects data which has site_type , region and building_id information
Step 3. Next use GET /api/prices?service_type=CLOUDPORT&service=GOOGLE_CLOUD&region={region}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth
Step 4. Call POST api/google/service/port with below payload

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " GOOGLE_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>",
  "building_id": ",building_id>",
  
}

where port_name is given port name price_id is retrieved from the prices api csp_key is of format uuid/region/zone provided by Google to the customer in Step 1. cloud_region Regions created by Google basis the data centre in a geography e.g. Asia pacific southeast 1 building_id is building identifier and both retrieved from the /cloudsites endpoint
Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/google/service/port/{port_id} to rename Google port

Delete Cloud Port

DELETE /api/google/service/port/{port_id} to delete the port

List Cloud Ports

Use GET /api/google/service/port

Retrieve a single Cloud Port information

Use GET api/google/service/port/{port_id}

Find related requests

Use GET api/google/request/port to retrieve Google port requests data. Retrieve the service Id using the session id and that can be used to retrieve the related requests

IBM Cloud DirectConnect

Add Cloud Port

To order IBM cloud port follow following steps
Step 1. Login to IBM portal.Select location then “Colt" as provider.Select the port bandwidth ( 50Mbps and 5Gbps).Select the rounting and the get the key. Enter the BGP routing details.Once the FastConnect service has been created, customers will be assigned a Service Key – this will be required to create a cloud port.
Step 2. Use GET /api/prices?service_type=CLOUDPORT&service=IBM_CLOUD to retrieve price for the given Region, Location and Bandwidth
Step 3. Call POST api/ibm/service/port with below payload

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " IBM_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>"
}

where port_name is given port name price_id is retrieved from the prices api csp_key is provided by IBM to the customer in Step 1. cloud_region is not needed for IBM cloud
Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/ibm/service/port/{port_id} to rename IBM port

Delete Cloud Port

DELETE /api/ibm/service/port/{port_id} to delete the port

List Cloud ports

Use GET /api/ibm/service/port to retrieve list of IBM Ports and related information

Retrieve a single Cloud Port information

Use GET api/ibm/service/port/{port_id}

Find related requests

Use GET api/ibm/request/port to retrieve IBM port requests data

Oracle Cloud FastConnect

Add Cloud Port

To order Oracle cloud port follow following steps
Step 1. Login to Oracle cloud portal.Select “Oracle Provider” and then “Colt DCA”.Select a “Private/Public” domain.Enter the FastConnect port bandwidth (1G-10G) Enter the BGP routing details.Once the FastConnect service has been created, customers will be assigned a Service Key – this will be required to create a cloud port.
Step 2. Use GET /api/prices?service_type=CLOUDPORT&service=ORACLE_CLOUD&region={region}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth
Step 3. Call POST api/oracle/service/port with below payload

{
  " port_name ": "< port_name>",
  " price_id ": "< price_id >",
  " cloud_provider ": " ORACLE_CLOUD ",
  " cloud_region ": "< cloud_region >",
  " csp_key ": "< csp_key>"
  "building_id": "<building_id>"
}

where port_name is given port name price_id is retrieved from the prices api csp_key is provided by Oracle as described in Step 1. cloud_region is the region chosen when the port was created
Refer a flowchart below for the process steps.

Rename Cloud Port

Use PUT /api/oracle/service/port/{port_id} to rename oracle port

Delete Cloud Port

DELETE /api/oracle/service/port/{port_id} to delete the port

List Cloud ports

Use GET /api/oracle/service/port to retrieve all Oracle ports

Retrieve single port data

Use GET /api/oracle/service/port/{port_id}

Find related requests

Use GET api/oracle/request/port to retrieve all the request

Equinix Fabric Interconnect

Add Cloud Port

To order an Equinix cloud port follow following steps
Step 1. Login to Equinix interface. Create Fabric interconnect service choosing Colt as a provider. Generate a service key.Use the SDN API.
Step 2. Use GET api/cloudsites to retrieve Equinix regions, interconnects data which has site_type , region and building_id information
Step 3. Next use GET /api/prices?service_type=CLOUDPORT&service=EQUINIX_CLOUD&region={region}&building_id={building_id} to retrieve price for the given Region, Location and Bandwidth
Step 4. Call POST /api/v2/equinix/services with below payload

{
  "price_id": <price_id>,
  "cloud_provider": "EQUINIX_CLOUD",
  "name": "<port_name>",
  "csp_key": "<csp_key>",
  "building_id": "<building_id>",
  "cloud_region": "<cloud_region>"
}

where price_id is retrieved from the prices api port_name is Port name given by customer csp_key is key provided by cloud provider to customer building_id is retrieved from cloudsites api cloud_region e.g. am for Amsterdam retrieved from cloudsites api

Rename Cloud Port

Use PATCH /api/v2/equinix/services/{id} to Rename the port with pay load {"new_name":"Equinixcloudport 11"} Where port id is port identification number and new_name is updated name

Delete Cloud Port

Use DELETE /api/v2/equinix/services/{id} to Delete the port

List Cloud ports

Use GET /api/v2/equinix/services to retrieve all ports data

Retrieve single port data

Use GET /api/v2/equinix/services/{id} to retrieve single port details

Find related requests

Use GET /v2/equinix/request/{id} get request data for particular port identifier
Refer a flowchart below for the process steps.

Connectivity

Use new API v2/connection/services to create,modify,delete and retrieve Ethernet connection

Ethernet connections

Connections are circuits that are routed between two On Demand ports. On Demand ports can be dynamically configured to support either Ethernet Private Line (“point to point”) based on transparent handover or Ethernet Virtual Private Line “(hub and spoke”) services based on a VLAN handover.

EPL and EVPL are not treated as different service types in the On Demand platform, although the services are configured differently.

On Demand connections support bandwidths between 10Mbps and 20Gbps. Higher bandwidths are available on request. The supported bandwidth of an On Demand circuit connection is based on the bandwidth of the ports at the A and B end points. This applies to both fixed term and flexible contracts.

For point to point (EPL) services where the A end and B end port speeds are equal, the circuit connection bandwidth is based on bandwidth ranges that are related to the speed of both ports.

The bandwidths that are supported for EPL configurations are 1 to 10 Gbps port range for all locations and 40 to 100Gbps port range for Key Data centre

For EVPL services the maximum circuit connection bandwidth is determined by the lower “unused” bandwidth on each port. For example, the supported bandwidth range for a circuit connection routed between a 10Gbps NNI and a 1Gbps B end port is 10Mbps-1Gbps (i.e. the range associated with the lower speed port).

Topology

Connections have three VLAN modes, which apply to each end of the circuit connection:

The supported combinations are shown in the below table (A end and B ends can be used interchangeably).

This section describes the APIs that are used to create, manage and cease Ethernet connections.

Create an Ethernet Connection

An Ethernet connection can be ordered only between two Ethernet ports . This section describes steps needed to create an Ethernet connections with bare minimum attributes. Specific case is discussed in Use cases section.
Step 1. Use GET /api/v2/port/services to find out the ports .
Step 2. Next retrieve the prices and products for connecting 2 ports using GET api/prices?service_type=ETHERNETCIRCUIT&from_port_id={from_port_id}&to_port_id={to_port_id} where the from and to port ids are retrieved from the earlier API call.
Step 3. To make a connection request, use POST /api/v2/connection/services the payload consists of

{
"from_port_id": "<from_port_id>",
"from_vlans": {
    "vlan_mapping": "<vlan_mapping>",
    "vlan_type": "<vlan_type>",
    "vlan_id": vlan_id
},
"name": "<connection_name>",
"price": {
    "price_id": <price_id>
},
"to_port_id": "<to_port_id>",
"to_vlans": {
    "vlan_mapping": "<vlan_mapping>",
    "vlan_type": "<vlan_type>",
    "vlan_id": vlan_id
}

Where connection_name is the name given to the connection, from_vlans and to_vlans has vlan_mapping e.g., “X” or “P” or “F”,vlan_type e.g. “S” or “C” (VLAN can be S-VLAN (88a8) or C-VLAN (8100) and vlanid ranging from 1 to 4094

Rename Ethernet Connection

Use PUT /api/v2/connection/services/{connection_id} to update the name of Ethernet connection with payload as name which is updated connection name

Delete Ethernet Connection

Use DELETE api/v2/connection/services/{connection_id} to delete an Ethernet

List Ethernet connections

Use GET api/v2/connection/services endpoint

Retrieve single Ethernet Connection Information

Use GET api/v2/connection/{connection_id}

Find related requests

Use GET /api/v2/connection/requests

Modify Bandwidth

Customer have an option to modify bandwidth OnDemand. The charges are based on the number of changes done. E.g. if 10MB service is advanced to 1GB for 20 minutes we charge for 1 hour.If the changes are made twice in a month.
Use PUT /api/v2/connection/services/{connection_id} to update the bandwidth by providing price_id which can be retrieved using GET /api/prices?service_type=ETHERNETCIRCUIT&connection_id={connection_id} and setting the appropriate coterminus_option

Modify VLAN configuration

Use PUT /api/v2/connection/services/{connection_id} to update the VLAN parameters connection with payload with updated VLAN parameters

Modify Contractual Commitment

Step1.
Use GET /api/prices?version=1&service_type=ETHERNETCIRCUIT&connection_id={connection_id}&version={updated_version_id}

Step 2.
Use PUT api/connection/services/{connection_id} with payload

{    
  "price_id": <price_id>,
  "coterminus_option": <coterminus_option>
}

Schedule Bandwidth Changes

This is only available for services with no commitment.
Retrieve prices using /api/prices?service_type=ETHERNETCIRCUIT&connection_id={connection_id} Use POST /api/schedule with payload

{
  "price_id": <price_id>,
  "connection_id": " <connection_id>",
  "event_frequency": "< event_frequency>",
  "event_date": "<event_date>"
}

Where event_frequency could be ONE_OFF, WEEKLY, MONTHLY etc

Create Cloud Connection

There is an ethernet port which is already created at “A end “ and at the B end a cloud port is used and a connection is ordered between them.

Below APIs are used in different steps to achieve a cloud connection
Step 1. Use GET /api/ports?available=true this provides ports those are already created For Google port use GET /api/google/service/port?available=true For IBM use GET /api/ibm/service/port?available=true For Oracle use GET /api/oracle/service/port?available=true For Equinix use GET /api/v2/equinix/service
Step 2. Use GET /prices?service_type=CLOUDCIRCUIT&from_port_id={from_port_id}&to_port_id={to_port_id}&to_port_id_2={to_port_id_2} where from_port_id (Ethernet port id) and to_port_id (Cloud port id) and to_port_id_2 is a secondary port data is retrieved from the /api/ports endpoint to_port_id_2 which is he secondary port id has to be provided only for Azure connection
Step 3. Use POST /api/connections with payload as below data elements

{
  "price_id": <price_id>,
  "connection_name": "<connection_name>",
  "component_connections": [
    {
      "from_port_id": "<from_port_id>",
      "to_port_id": "<to_port_id>",
      "cloud_provider_from_port": "<cloud_provider_from_port>",
      "cloud_provider_to_port": cloud_provider_to_port,
      "a_end_vlan_mapping": "<a_end_vlan_mapping>",
      "b_end_vlan_mapping": "<b_end_vlan_mapping>",
      "a_end_vlan_type": "<a_end_vlan_type>",
      "b_end_vlan_type": "<b_end_vlan_type>",
      "a_end_vlan_ids": [],
      "b_end_vlan_ids": []
    }
  ]
}

For Azure use cloud_provider_from_port= AZURE_EXPRESS For Google use cloud_provider_from_port= GOOGLE_CLOUD For IBM use cloud_provider_from_port= IBM_CLOUD For Oracle use cloud_provider_from_port= ORACLE_CLOUD

For Equinix cloud cloud_provider_from_port is EQUINIX_CLOUD. For AWS Dedicated cloud_provider_from_port is AWS_DEDICATED For AWS HOSTED cloud_provider_from_port is AWS_HOSTED

Rename Cloud Connection

Use PUT /api/connections/{connection_id} to update the name of connection with payload as name which is updated connection name

Delete Cloud Connection

Use DELETE api/connections/{connection_id} to delete Cloud Connection

List Cloud connections

Use GET api/connections endpoint with attribute is_cloud_connection=true in the response

Retrieve single cloud Connection Information

Use GET api/connections/{connection_id}

Find related requests

Use GET /api/requests and in the result search for requests which has resource as “CONNECTION” and id is the connection id and is_cloud=true

Modify Bandwidth

Use PUT /api/connections/{connection_id} to update the bandwidth by providing price_id which can be retrieved using GET /api/prices?service_type=CLOUDCIRCUIT&connection_id=

Modify VLAN configuration

Use PUT /api/connections/{connection_id} to update the VLAN parameters connection with payload with updated VLAN parameters

Modify Contractual Commitment

Step1. Use GET /api/prices?version=1&service_type=CLOUDCIRCUIT&connection_id={connection_id}&version={updated_version_id}
Step 2. Use PUT api/connections/{connection_id} with payload

{
  "price_id": <price_id>,
  "coterminus_option": < coterminus_option>,
  "is_cloud_connection": < is_cloud_connection >
}

where is_cloud_connection = true

Schedule Bandwidth Changes

This is only available for services with no commitment.
Retrieve prices using /api/prices?service_type=CLOUDCIRCUIT&connection_id={connection_id} and use POST Use POST /api/schedule with payload

{
  "price_id": "<price_id>",
  "connection_id": " <connection_id>",
  "event_frequency": "< event_frequency>",
  "event_date": "<event_date>"
}

event_frequency could be ONE_OFF, WEEKLY, MONTHLY etc

Create IP Access Connections

IP Access provides a dedicated permanent access to the public Internet. Colt IP Access allows customers to connect business sites of all sizes to the Internet easily, efficiently and securely with guaranteed IP bandwidth. It is a wires-only service with PA IPv4 /29 addresses only and customers need to provide a router.

Add an IP Access Connection

IP Access on Demand - On Demand internet connectivity is the commercial offering supported by following set of API. The A end is Ethernet port and B end is internet connectivity.
Step 1. Use GET /api/v2/port/services to find the Ethernet ports that are already created

Step 2. Retrieve IP Access products and prices that could be available for the port using /api/prices?service_type={service_type}&from_port_id={from_port_id} where service_type= IPACCESS_CIRCUIT and from_port_id is retrieved from earlier API call

Step 3. Call POST /api/ipaccess/request with payload

{
  "action": "CREATE",
  "price_id": <price_id>,
  "connection_name": "<connection_name>",
  "from_port_id": "<from_port_id>",
  "port_vlan_mapping": "< port_vlan_mapping >",
  "port_vlan_type": "< port_vlan_type >",
  "port_vlan_ids": [
    {
      "from_id_range": < from_id_range>,
      "to_id_range": < to_id_range >
    }
  ]
}

where price_id retrieved from prices api, connection_name is name given to connection, from_port_id is ethernet port id, port_vlan_mapping e.g. “X”, port_vlan_type e.g. ”C”, from_id_range and to_id_range number of VLAN port ids

Rename IP Access connection

Use PUT /api/ipaccess/service/{connection_id} and payload as connection_name which is updated name for the connection.

Delete IP Access Connection

Use POST /api/ipaccess/request with payload{"action":"DELETE","connection_id":""}

List IP Access Connections

Use GET /api/ipaccess/service to retrieve IP Access connections where available is mandatory query parameter

Find related requests

Use GET /api/ipaccess/request

Modify Bandwidth

Step 1. Retrieve price using GET /api/prices?service_type={service_type}&connection_id={connection_id} where service_type = IPACCESS_CIRCUIT
Step 2. Call /api/ipaccess/request with payload

{
  "action":"<action> ",
  "price_id":<price_id>,
  "coterminus_option":< coterminus_option>,
  "connection_id":"<connection_id>"
} where action = UPDATE

Modify VLAN Configuration

Call POST [api/ipaccess/request] (#post-/ipaccess/request) with payload

{
  "action": "<action>",
  "connection_id": "<connection_identifier>",
  "port_vlan_mapping": "< coterminus_option >",
  "port_vlan_type": "< port_vlan_type >",
  "port_vlan_ids": [
    {
      "from_id_range": "<VLAN_ID>",
      "to_id_range": "<VLAN_ID>"
    }
  ]
}

where action= UPDATE , port_vlan_mapping = X, port_vlan_type= C and VLAN_ID= numerical VLAN id

Modify Contractual Commitment

Step 1. call GET /api/prices?version=1&service_type=IPACCESS_CIRCUIT&connection_id={connection_id}&version={updated_version_id}
Step 2. call POST api/ipaccess/request/ with payload

{
  "action": "<action>",
  "price_id": <price_id>,
  "coterminus_option": <coterminus_option>,
  "connection_id": "<connection_id>"
}

Retrieve IP Access Connection Information

Use GET api/ipaccess/request/{request_id}

Retrieve related requests

Use GET api/ipaccess/request/ retrieve the service_id from the session and find out the related requests

Cross-connects

Customers can request a fibre cross connect in a data centre via the On Demand platform, which will result in Colt placing a request on the data centre operator for a cross connect between the specified On Demand port and the demarcation point in the customer rack.

Please note that only fibre cross connects are supported - copper cross connects are not supported.

Where a cross connect is requested, customers are required to enter the demarcation details and are also required to upload a letter of authority to grant Colt permission to place a cross connect order to the customer rack. The demarcation details and LOA (pdf file format) are mandatory. Cross-connects require a physical installation and therefore are a manual operation that does not complete in ‘real-time’. The standard lead times apply for Cross-connect orders. This section describe the APIs used to create, display, delete and retrieve associated requests data for a given cross connect

Add Cross-connect

Cross connects can only be added on already added Ports. Following steps are needed to request a cross connect
Step 1. Create an ethernet port at a location where cross connects has to be ordered refer steps in Add an Ethernet Port
Step 2. Retrieve charges for a cross connect at a building Use /api/prices?service_type=CROSSCONNECT&building_id={building_id}
Step 3. Use POST api/cross_connect with payload as

{
  "port_request_id": "< port_request_id>",
  "port_id": "<port_id>",
  "customer_pp_port": "< customer_pp_port >",
  "customer_pp_floor": "< customer_pp_floor>",
  "customer_pp_room": "< customer_pp_room>",
  "customer_pp_cabinet": "< customer_pp_cabinet>",
  "customer_pp_rack": "< customer_pp_rack>",
  "customer_pp_device": "< customer_pp_device >",
  "customer_pp_slot": "< customer_pp_slot>",
  "customer_pp_connector": "< customer_pp_connector >",
  "loa": "<loa>",
  "price_id": "<price_id>",
  "connector": "<connector>"
}

PP is presentation panel, port_request_id is the request id of the port created in Step 1. port_id is the service_id of the port created in Step 1, price_id is retrieved from Step 2, loa is letter of authority, connector is connector used in Ethernet port

Delete cross connect

Use DELETE api/cross_connect/{id} to delete a cross connect where id is cross_connect identifier

List Cross-connects

Use GET api/cross_connect to retrieve list of cross connect and related data connections data

Retrieve Cross-connect Information

Use GET api/cross_connect/{id} to retrieve data for single cross connection where id is cross_connect identifier

Find Related Requests

Use GET /api/requests and search for requests which has resource as “CROSSCONNECT” and id is the port id

Retrieve Billing Data

Use GET charges to retrieve all the charges associated with Ports, Connections and Boosted bandwidths for Cloud, Ethernet and IP Access connections for a given customer

Retrieve service related charges

Use GET api/charges to retrieve all the charges associated with Ports, Connections for a given customer. The response contains information about recurring, one off , penalty charges associated with connection, port or IP Access connection.

Provide Bandwidth Boost

Bandwidth Boost feature enables temporary bandwidth upgrades on connections with a commitment term, allowing them to change the bandwidth back to the original committed bandwidth when they choose. Therefore, a customer could buy a 100M service on a 36-month contract, and at any time during that period decide to boost the service above 100M as much as required, paying a premium, to eventually downgrade back to the original 100M bandwidth and rate. The feature is available for Ethernet, Cloud and IP Access connections.

Retrieve Bandwidth boost options for connection type

Use GET /api/prices?service_type={service_type}&from_port_id={from_port_id}&to_port_id={to_port_id} where service_type=Ethernet or cloud or ipaccess connection. The rental_boost_charge and bandwidth_mb in the response gives price and bandwidth value.

Apply Bandwidth boost to existing connection

Step 1. Retrieve bandwidth boost options and associated prices using GET /api/prices?service_type={service_type}&connection_id={connection _id} where service_type is ETHERNETCIRCUIT or CLOUDCIRCUIT or IPACCESS_CIRCUIT and connection_id is connection identifier for the connection. The bandwidth_boost_prices array returns required values.

Step 2. Use PUT /api/connections/{connection_id} with request payload attribute boost_bandwidth_mbps as query param

List available Bandwidth Boost and prices for a connection

Use GET /api/connections search for rental_boost_charge and bandwidth_mb which represent the bandwidth and its corresponding charges at a given date.

Find Boosted bandwidth for connection

Use Get /api/connections check for base_bandwidth and bandwidth values and if they are different use the bandwidth value as boosted value

Find Boosted bandwidth requests

Use GET /api/requests and look for record where resource=CONNECTION and action=BOOST. If this value is present then the bandwidth value will be the boosted bandwidth and the base_bandwidth attribute will be unboosted bandwidth, old_bandwidth will show the value prior to this request.

Charges associated with bandwidth boost

Use GET /api/charges. boost_charges array will have amount, date on whihc boost was applied and type=BOOST values.

Retrieve Trouble tickets data

Use GET tickets to retrieve all the trouble tickets raised by system or service desk and provide view of status on each one of them to your customer.

Retrieve tickets data

Use GET api/tickets to retrieve all the tickets information

Manage multiple customers accounts

If you have multiple customer accounts associated to your login, you have a possibility to use any one of them at a time. You can then manage the services associated with that customer account.
To see which accounts are associated with your login use GET /api/v3/user.
To set a particular customer account as a preffered customer use PATCH /api/v2/user
To view terms and condition details for associated customer account use GET /api/v2/legal_requirements and provide 2 letter language code as request parameter as preferred_language e.g. "DE"
To accept terms and condition for an associated customer account use PATCH /api/v2/legal_requirements and provide the input payload as

{
"id": 49652,
"accepted": true
}

End-to-end use-cases

This section covers the end-to-end use cases that are developed using building blocks like Ethernet and cloud ports. These also cover usage of fetures like location retrieval, product attributes to determine the prices for connectivity.

Create Point to Point connection

1. Create a-end ethernet port
2. Create b-end ethernet port
3. Create ethernet connection with P-P VLAN mapping.

Step 1. Add two Ethernet port
Step 2. Make Ethernet connection with payload

{
  
"from_port_id": "<from_port_id>",
"from_vlans": {
  "vlan_mapping": "P",
  "vlan_type": "",
  "vlan_id": null
},
"name": "P2Pconnection",
"price": {
  "price_id": <price_id>
},
"to_port_id": "<to_port_id>",
"to_vlans": {
  "vlan_mapping": "P",
  "vlan_type": "",
  "vlan_id": null
}

}

Where vlan_mapping are “P” for both from and to port Refer P2P section of the Ethernet connection

Create Hub and Spoke connection

1. Create b-end ethernet port

2. Create ethernet connection with X-P or X-X (x on hub end)or F-F mapping

Step1 and Step 2 is adding two ethernet ports
Step 3. Make an Ethernet Connection where change in payload values from_vlans - vlan_mapping is “X” and to_vlans - vlan_mapping is “P” or both as “X” or “F” at both.Refer Ethernet Virtual Private Line section of Ethernet connection

Order bundle for Ethernet (New*)

Currently the On Demand platform allows users to place Port and Connection requests. However for a Connection request both end ports need to be already live and active. This means that if customers want to place an order for a connection which requires new capacity to be built, they need to wait weeks/months until both ports are delivered before they can place the Connection request. This feature therefore will allow customers to place all required requests for a connection at the same time in one action, with each request triggering automatically once all the pre-requisites are completed.

This means that customers in one single action can submit:

1. A port create request for the a-end by using POST /api/v2/port/services operation
2. A port create request for the b-end again using POST /api/v2/port/services operation and
3. Submit a connection request between the a-end and b-end ports using POST /v2/connection/services operation while the ports are still getting created to achieve this.

Create a Cloud Connection

This is made of 3 steps:

1. Create a cloud port
2. Create an ethernet port (optional if already available)
3. Create a cloud connection Refer Cloud connections

Create an IP Access Connection

This is made of 2 steps:

1. Create an ethernet port
2. Create an IP access connection. Refer IP Access section

Cross connect

1. Add ethernet port

2. Add cross connect

Address qualification

Step 1. Search for buildings from customer address book use GET /api/locations just to confirm that the building is not already added to the address book
Step 2. Search building/location where Port has to be ordered in the global directory use GET /api/global_directory/address
Step 3. Search for Sites available in the building using GET /api/building/{building_id}/site
Step 4. Add the building to address book using POST /api/locations with payload

{
  "building_id": "<building_id",
  "location_name": "<location_name>",
  "country": "<country_name>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

Where the site_floor and site_room_name has to be provided if the site is newly added else will be already available in the building details and will be available as a response of step 3.
Exception scenario
If the address is not available in Colt database then the result of Step 2 will be an empty array Use GET /api/geolocation-reachable?lat={latitude}&long={longitude}&place_id={place_d}

If the Address is reachable API responds with

{
  "nearnet_price_id":<nearnet_price_id>,
  "reachable": true,
  "installation_currency": "<currency>",
  "installation_charge": <charge>
}

If not then Colt connection is not supported at the location. Add the building to Address book Use POST /api/locations with payload

{  
"location_name": "<location_name>",
  "city": "<city>",
  "country": "<country>”,
  "latitude": <latitude>,
  "longitude": <longitude>,
  "address": ",address>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

Refer a flowchart below for the process steps.

Add new site to building

Step1. Search for a site availability at a given building use GET api/building//site this should result in empty site data array
Step 2. To add a new site use POST /api/locations

{
  "building_id": "< building_id >",
  "location_name": "< location_name >",
  "country": "<country_name>",
  "site_floor": "<site_floor>",
  "site_room_name": "<site_room_name>"
}

where site_floor is the new floor number and site_room_name is new site name where port has to be installed. This API returns "id":"”, “novitas_site_type":" “ which are used in further process of price retrieval

Find Prices for ordering a Port or making a connection

To Find prices for installing an Ethernet Port and a connection between 2 port following steps are used
Step 1. Get the building details where A end port has to be installed using /api/global_directory/address?place_id=ChIJH8vQ7fmLGGAR_Vx9A5i46pc&count=100 discussed in step 1. Of Add Ethernet Connection section. This API will return null if connected building is not available.
Step 2. Retrieve prices and products available for Ethernet port at the given building using GET /api/prices?service_type=ETHERNETPORT&site_type={site_type} where site_type is retrieved from step 1. which is novitas_site_type
Step 3. Choose B End as Ethernet port similar to Step 2 and retrieve the prices
Step 4. Retrieve prices for making an Ethernet connection between these two ports using GET /api/prices?service_type=ETHERNETCIRCUIT&from_site_type={from_site_type}&to_site_type={from_site_type} where from_site_type and to_site_type are retrieved from the Step 1
To find Price to make IP Access Connection following steps are used
Step 1. Get the Ethernet port installations product and charges for the chosen building
Step 2. Retrieve product and prices for IP Access connection using
GET /api/prices?service_type=IPACCESSCIRCUIT&site_type={site_type}
To find Prices for cloud connection
Step 1. Retrieve all the information about the cloud providers using GET /api/cloudsites
Step 2. Retrieve Product and prices for port installation using GET /prices?service_type=CLOUDPORT&site_type=DCA-MSA-JP-TKY where site_type is retrieved from step 1
Step 3. Retrieve prices for making cloud connection at the given port api/prices?service_type=CLOUDCIRCUIT&from_site_type={from_site_type}&to_site_type={to_site_type}&to_site_type_1={to_site_type _1}&service=AZURE_EXPRESS where from_site_type is cloud END retrieved in step 1 and to_site_type is the A END Ethernet port of the network

Note for other cloud providers service attribute changes according to provider and to_site_type_1 attribute is not needed.

Terminology

• CEA - Common Equipment Area
• Coterminus option: When changing a connection in some chargeable way, this option defines whether the new contract should run only until the end date of the current contract (true), or whether you want to “reset” the contract period to start from the date of the change”.
• Cross Connect: A cross-connect is a physical, hardwired cable that provides a direct connection between two different termination locations within a data centre. the letter of authority is NOT provided by the datacentre owner, it has to be provided by the owner of the equipment you are connecting to, i.e. Colt if the customer orders the cross-connect and the customer if Colt orders it.
• Global directory: Information of buildings where Colt’s connectivity is available
• LOA: Letter of authority provided to install connection
• MMR: Meet me room
• novitas_site_type: Is a Colt term to represent a site e.g. KDC-PL-WOW created by combining the building category (KDC, DCNET, LANLINK, DCA-MSA, DCA-AWSH, etc), PL 2 letter country code and WOW 3 letter metropolitan area code.
• Order id: This is generated by Siebel for siteport and cross-connect requests
• PORT_TYPE: DCNPORT/LANPORT/DCAPORT - DCNPORTs are located in data centres. LANPORTs are located on customer premise. DCAPORTs are cloud ports.
• Product: Colt products e.g. Twisted pair electrical 1Gbps ethernet port
• Request ID- Request identifier is created for every state chnage of connection e.g. create,modify,delete.
• Service ID- A unique reference to a service the customer has paid for/requested from the time it is created until the time it is terminated. Applies to all Ports & Connections.
• Service Type: Connectivity prices are derived basis Service types e.g. ETHERNETPORT'' , CROSSCONNECT or ''ETHERNETCIRCUIT
• Shared area: This is a place where along with other providers Colt connectivity can be provided
• Site: Location in the building where ports can be installed.
• SITEPORT: This is a request type which only installs the capacity – this will also create a PORT request to reserve the capacity once it has been delivered.
• VLAN type: S-VLAN (88a8) or C-VLAN (8100)