Console Connect logo

Layer 2 Connections

Once a port is active, you can provision a connection on it. You can create Layer 2 Connections between your port and another port belonging to your company (self-to-self), to a port belonging to another company (B2B), or to a DCP port.

Connections can be in one of the following states:

Status Description
PENDING The connection request is pending approval from at least one party.
CANCELLED The request was cancelled by the source/requestor.
PENDING ACCEPTANCE Pending acceptance by 3rd party service (e.g. AWS).
DENIED The request was rejected by the target.
ACCEPTED The request was accepted by the target, but the physical port has not yet come up.
ACTIVE The connection is Active and operational.
DISABLED The connection has been explicitly disabled.
DELETING The connection is in the process of being deleted.
DELETED The connection has been deleted.
MANUAL The connection is being manually provisioned.
ERROR The connection is in an error state. Refer to connection.errorReason for more information.

Create a Layer 2 connection request

Create a Layer 2 connection request to a specified destination company. Layer 2 connections require a source port ID and requested metro.

  • You may not create an outgoing connection request that exceeds your port utilization or plan entitlement.
  • Both parties must approve a connection before it is activated. When either party makes a billing or capacity change, the other party must approve the connection using the approve endpoint.
  • The 'paymentType' can only be 'invoice'. A 'paymentType' of 'creditcard' is only supported via the Console Connect web application.
  • For pay-as-you-go connections where paymentType is 'creditcard', paymentTransactionId, duration and evergreen options must be provided in the request.
  • If paymentType is 'invoice', 'destDcf', 'duration' and 'durationUnit' should be provided.
Securityapi-key
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
Request Body schema: application/json
required
type
required
string

The connection type, typically "LAYER_2".

Value: "LAYER2"
name
required
string

The name of the new connection.

portId
required
string

The source port ID.

destPortId
required
string
regionId
string
destRegionId
string
destDcf
string
speed
required
number

The port speed in Mbps.

destMetroId
required
string

The ID of the destination metro.

destCompany
required
string

The username of the destination company.

paymentType
required
string

The PAYG payment type.

Enum: "creditcard" "invoice"
duration
required
number
durationUnit
required
string

The duration unit for the connection ('d', 'w', 'm', 'y').

evergreen
boolean
classOfService
required
string
Enum: "GOLD" "SILVERPLUS" "SILVER" "BRONZE"
srcVlanRequest
number or null
destVlanRequest
number or null
discountCode
string
Responses
200

OK

put/api/v2/company/{username}/connections/layer2
Request samples
application/json
{
  • "type": "LAYER2",
  • "name": "my new connection",
  • "portId": "123",
  • "speed": 1000,
  • "paymentType": "invoice",
  • "duration": 1,
  • "durationUnit": "m",
  • "destPortId": "d466b388d3e9ee0a92177910",
  • "destCompany": "companyusername"
}
Response samples
application/json
{
  • "id": "58afc0499430ab7f3666b990",
  • "type": "LAYER2",
  • "status": "CREATING",
  • "srcRegionId": "236107000000000000000001",
  • "destRegionId": "236107000000000000000001",
  • "updatedAt": "2017-02-24T05:10:44.942Z",
  • "createdAt": "2017-02-24T05:10:33.807Z",
  • "speed": {
    },
  • "subconnections": [ ],
  • "vlan": {
    },
  • "name": "my new connection",
  • "cdrBillingType": "METRO",
  • "payg": true,
  • "billingType": [
    ],
  • "classOfService": "BRONZE"
}

Read a Layer 2 connection

Securityapi-key
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

get/api/v2/company/{username}/connections/{connectionId}
Response samples
application/json
{
  • "id": "58afc0499430ab7f3666b990",
  • "name": "my connection",
  • "status": "ACTIVE",
  • "type": "LAYER2",
  • "speed": {
    },
  • "srcRegionId": "236107000000000000000001",
  • "destRegionId": "236107000000000000000001",
  • "updatedAt": "2017-02-24T05:10:44.942Z",
  • "createdAt": "2017-02-24T05:10:33.807Z",
  • "tag": null,
  • "deleted": false,
  • "deletedAt": "1970-01-01T00:00:00.000Z",
  • "subconnections": [ ],
  • "srcCompany": [
    ],
  • "destCompany": [
    ],
  • "metro": [
    ],
  • "destMetro": [
    ],
  • "port": [
    ],
  • "cdrBillingType": "METRO",
  • "payg": true,
  • "billingType": [
    ],
  • "maintenanceMode": false,
  • "srcVlanRequest": 1000,
  • "destVlanRequest": 2000,
  • "classOfService": "GOLD",
  • "vlan": [
    ],
  • "request": [
    ]
}

Delete a Layer 2 connection

Securityapi-key
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

delete/api/v2/company/{username}/connections/{connectionId}

Update a connection

Update a Layer 2 connection

This is used for both connection requests and regular connection edits.

Connection speed

To prevent unexpected costs for the other party, you may only reduce the speed of a connection to another company (either as a connection request or after it has been activated).

Self-connections can be updated to a new speed at any time.

The speed of connection groups may not be updated.

Securityapi-key
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Request Body schema: application/json
required
speed
number >= 1

Speed in Mbps. You can set any speed while the connection request is PENDING. After the connection has been accepted by both parties, the connection speed can be reduced at any time, but may not be increased without a change request.

name
string

Friendly name for this connection. This is specific to your company, however when first creating a connection request this name will set for bot your company and the destination company.

portId
string

Connection request: Port ID to use for this connection. If changing the controller would change the cdrBillingType for the other person, they will need to approve this connection request again.

untagged
boolean

Connection request: Whether this connection should be untagged.

destUntagged
boolean

Connection request: Whether the destination should be untagged. Only used for self-connection.

destPortId
string

Connection request: Dest port ID to use for a self-connection.

controllerId
string

Connection request: Controller ID to use for this connection. Only allowed on Layer 3 connections. If changing the controller would change the cdrBillingType for the other person, they will need to approve this connection request again.

destControllerId
string

Connection request: Dest controller ID to use for a self-connection.

Responses
200

OK

post/api/v2/company/{username}/connections/{connectionId}
Request samples
application/json
{
  • "speed": 1,
  • "name": "string",
  • "portId": "string",
  • "untagged": true,
  • "destUntagged": true,
  • "destPortId": "string",
  • "controllerId": "string",
  • "destControllerId": "string"
}
Response samples
application/json
{
  • "id": "58afc0499430ab7f3666b990",
  • "name": "my connection",
  • "status": "ACTIVE",
  • "type": "LAYER2",
  • "speed": {
    },
  • "srcRegionId": "236107000000000000000001",
  • "destRegionId": "236107000000000000000001",
  • "updatedAt": "2017-02-24T05:10:44.942Z",
  • "createdAt": "2017-02-24T05:10:33.807Z",
  • "tag": null,
  • "deleted": false,
  • "deletedAt": "1970-01-01T00:00:00.000Z",
  • "subconnections": [ ],
  • "srcCompany": [
    ],
  • "destCompany": [
    ],
  • "metro": [
    ],
  • "destMetro": [
    ],
  • "port": [
    ],
  • "cdrBillingType": "METRO",
  • "payg": true,
  • "billingType": [
    ],
  • "maintenanceMode": false,
  • "srcVlanRequest": 1000,
  • "destVlanRequest": 2000,
  • "classOfService": "GOLD",
  • "vlan": [
    ],
  • "request": [
    ]
}

Approve a connection request

When both parties have approved the connection request, the connection will be created. Connections are automatically approved when a party updates the connection request.

Securityapi-key
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

put/api/v2/company/{username}/connections/{connectionId}/approve

Reject a connection request

Securityapi-key
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

put/api/v2/company/{username}/connections/{connectionId}/reject

Disable a connection

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company to check is following the other.

Example: Acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

put/api/company/{companyName}/connections/{connectionId}/disable
Response samples
application/json
{
  • "type": "LAYER2",
  • "name": "string",
  • "srcPortId": "string",
  • "speed": {
    },
  • "destMetroId": "string",
  • "destCompany": "string",
  • "destPortId": "string",
  • "paymentType": "creditcard",
  • "partner": {
    }
}

Enable a connection

Before a connection can be enabled, the source and destination ports must both be in the 'ACTIVE' state.

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company to check is following the other.

Example: Acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

put/api/company/{companyName}/connections/{connectionId}/enable
Response samples
application/json
{
  • "type": "LAYER2",
  • "name": "string",
  • "srcPortId": "string",
  • "speed": {
    },
  • "destMetroId": "string",
  • "destCompany": "string",
  • "destPortId": "string",
  • "paymentType": "creditcard",
  • "partner": {
    }
}

Change request

When you need to make a change that affects the other end of the connection, you must make a change request so that both parties can approve the change. The workflow of a change request is as follows:

  1. Company A creates a change request with a speed increase. Company A automatically approves this change. The connection.request.status will be set to PENDING.
  2. Company B can accept this change as-is and the change will be made. If company B modifies the change request, Company B automatically approves this change and company A's prior approval is removed.
  3. The change request goes back and forth between companies until it is approved by both sides, or rejected outright by one of the parties. The following connection properties are currently supported:
  • 'speed'

    Note: Speed decreases are allowed at any time. If a change request is made, the destination company can accept the change at a lower speed than the one specified.

You will need to have your 'companyId' handy. If you cannot remember your 'companyId', you can make a request to find it.

Create or update a change request

Create a change request. This will send an alert to the other party to approve.

The change request must be within the bounds of your port speed and Committed Data Rate (CDR). The bandwidth amount will be deducted from your entitlement (including global CDR) as soon as the request is made, reserving it for when the other party accepts the connection.

Use this endpoint to reduce the speed of an existing change request. If the other company has approved the change and you reduce the speed, the change will be applied automatically.

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company creating the connection.

Example: Acme
connectionId
required
string

The connection id

Example: 55767b5652a693344a015744
Request Body schema: application/json
required
speed
number
Responses
200

OK

put/api/company/{companyName}/connections/{connectionId}/change
Request samples
application/json
{
  • "speed": 250
}
Response samples
application/json
{
  • "type": "LAYER2",
  • "name": "string",
  • "srcPortId": "string",
  • "speed": {
    },
  • "destMetroId": "string",
  • "destCompany": "string",
  • "destPortId": "string",
  • "paymentType": "creditcard",
  • "partner": {
    }
}

Reject or cancel a change request

Reject or cancel a change request.

After performing this action, the 'request.status' will be set to either 'WITHDRAWN' if this is a change you proposed, or 'REJECTED' if this is a change the other party proposed.

An alert will be sent to the other party advising them of this change.

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company deleting the connection.

Example: Acme
connectionId
required
string

The connection id

Example: 55767b5652a693344a015744
Responses
200

OK

delete/api/company/{companyName}/connections/{connectionId}/change
Response samples
application/json
{
  • "type": "LAYER2",
  • "name": "string",
  • "srcPortId": "string",
  • "speed": {
    },
  • "destMetroId": "string",
  • "destCompany": "string",
  • "destPortId": "string",
  • "paymentType": "creditcard",
  • "partner": {
    }
}

Approve the current change request

Approve a change request. If both parties have approved this change request, the change will be applied automatically.

If you wish to accept a connection at a different speed, use the Create or update a change request endpoint.

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company creating the connection.

Example: Acme
connectionId
required
string

The connection id

Example: 55767b5652a693344a015744
Responses
200

OK

put/api/company/{companyName}/connections/{connectionId}/change/approve
Response samples
application/json
{
  • "type": "LAYER2",
  • "name": "string",
  • "srcPortId": "string",
  • "speed": {
    },
  • "destMetroId": "string",
  • "destCompany": "string",
  • "destPortId": "string",
  • "paymentType": "creditcard",
  • "partner": {
    }
}

Mark the change request as read

Mark a change request as read. This does not alter the change request, and will not allow the other side to see that you have marked it as read. This is a cosmetic change, and is only used to maintain state on the front-end.

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company creating the connection.

Example: Acme
connectionId
required
string

The connection id

Example: 55767b5652a693344a015744
Responses
200

OK

put/api/company/{companyName}/connections/{connectionId}/change/read
Response samples
application/json
{
  • "type": "LAYER2",
  • "name": "string",
  • "srcPortId": "string",
  • "speed": {
    },
  • "destMetroId": "string",
  • "destCompany": "string",
  • "destPortId": "string",
  • "paymentType": "creditcard",
  • "partner": {
    }
}

Sync connection with upstream provider

Sync the connection with the upstream provider. This is implemented for AzureExpressRoute, and will fetch the latest information from the Azure API. Use this when you have changed the connection speed & details in Azure and need to sync them back to Console Connect.

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company syncing the connection.

Example: Acme
connectionId
required
string

The connection id

Example: 55767b5652a693344a015744
Responses
200

OK

put/api/company/{companyName}/connections/{connectionId}/sync

Request connection logs

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company to check.

Example: Acme
connectionId
required
string

The connection id

Example: 55783e39519d254d36f6126e
Responses
200

OK

get/api/company/{companyName}/connections/{connectionId}/log
Response samples
application/json
{
  • "results": [
    ]
}

Get connection utilization data

Securityapi-key
Request
path Parameters
companyName
required
string

The username of the company that owns the connection to be checked.

Example: corp
connectionId
required
string

The connection id

Example: 55767b5652a693344a015744
query Parameters
start
required
string

Unix timestamp for beginning of time window.

Example: start=1459376516
end
required
string

Unix timestamp for end of time window.

Example: end=1459376516
resolution
required
string

Set the resolution of the response ('day' | 'hour' | 'minute'). If no resolution is passed, it will default to 'minute'. Note: As 'minute' is the smallest resolution, it will not have min/max fields in the response.

Example: resolution=day
Responses
200

OK

get/api/company/{companyName}/connections/{connectionId}/utilization
Response samples
application/json
{
  • "connectionId": 120391239323,
  • "results": [
    ],
  • "unit": "Mbps"
}
➔ Next to Alibaba Cloud