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.

Request a Layer 2 Connection to a Company

Layer 2 connection requests must include type, name, portId, speed, destMetroId, and destCompany, with LAYER2 specified as the type and the speed in Mbps.

curl \
--request PUT \
--header "portal-token: [[auth token]]" \
--header "Content-Type: application/json" \
--data-binary "{\"type\":\"LAYER2\",\"name\":\"Layer 2 Connection\",\"portId"\:\"576247795c9de0b91e8b8576\",\"speed\":10,\"destMetroId\":\"1232413986c08c061dd8c45f\",\"destCompany\":\"CompanyA\"}" \
https://api.consoleconnect.com/api/v2/company/:username/connections/layer2

Retrieve a List of all Connections

curl \
--header "portal-token: [[auth token]]" \
--header "Content-Type: application/json" \
https://api.consoleconnect.com/api/company/:companyName/connections

Update a Connection

curl \
--request POST \
--header "portal-token: [[auth token]]" \
--header "Content-Type: application/json" \
--data-binary "{\"name\":\"Connection 1\" }" \
https://api.consoleconnect.com/api/company/:companyName/connections/:connectionId

More information on Connections

Handle Incoming Connection Requests

Actions that may per performed on a connection request are: 'approve', 'reject', 'enable' and 'disable'. To approve an incoming connection request, pass the target companyName and connectionId to the following URL:

curl \
--request PUT \
--header "portal-token: [[auth token]]" \
--header "Content-Type: application/json" \
--data-binary "{\"destPortIt\":\"portId\"}" \
https://api.consoleconnect.com/api/v2/company/:companyName/connections/:connectionId/approve

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. #I don't see Metro anywhere in the examples, just a dest company and port id

  • 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.
  • You can optionally create an untagged connection by specifying untagged: true. This will place the port into single service mode, so you must ensure no other connections exist on the port before continuing.
  • You can optionally create a QinQ connection by specifying qinQ: true.
  • The 'paymentType' can be either 'invoice' or 'plan'. 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.
Request
path Parameters
username
required
string

The username of the company creating the connection.

Example: acme
Request Body schema: application/json
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
string
regionId
string
destRegionId
string
destDcf
string
speed
required
number

The port speed in Mbps.

destMetroId
string

The ID of the destination metro.

destCompany
string

The username of the destination company.

paymentType
string

The PAYG payment type.

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

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

evergreen
boolean
classOfService
string
Enum: "GOLD" "SILVERPLUS" "SILVER" "BRONZE"
number or (any or null)
number or (any or null)
discountCode
string
Responses
200

OK

put/api/v2/company/{username}/connections/layer2
Request samples
application/json
[
  • {
    }
]
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

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

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.

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
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.

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

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

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.

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.

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
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.

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.

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.

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.

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

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": [
    ]
}

Wanted Connection

Get a list of connections you would like to make with other companies, or that other companies would like to make with you.

Get by direction

Request
path Parameters
username
required
string

The username of the company.

Example: acme
direction
required
string

One of 'in' or 'out'. Inbound connections show people wishing to connect with you. Outbound connections are connections you wish to make with others.

Example: in
Responses
200

OK

get/company/{username}/connections-wanted/{direction}
Response samples
application/json
{
  • "results": [
    ]
}

Create a wanted connection

Express interest in connecting with the specified company. This will send a notification when the company becomes available for interconnecting.

Request
path Parameters
username
required
string

The username of the company expressing interest.

Example: acme
direction
required
string

You may only create an outbound connection.

company
required
string

The company to express interest in connecting with.

Responses
200

OK

put/company/{username}/connections-wanted/{direction}/{company}
Response samples
application/json
{
  • "results": [
    ]
}

Delete a wanted connection

Delete an expression of interest in connecting with a company or being connected to.

Request
path Parameters
username
required
string

The username of your company.

Example: acme
direction
required
string

One of 'in' or 'out'. Inbound connections delete a connection people want to make with you, whereas outbound connections deletes a connection you wish to make with others.

Example: in
company
required
string

The company on the other end of the proposed connection.

Example: Acme
Responses
200

OK

delete/company/{username}/connections-wanted/{direction}/{company}
Response samples
application/json
{
  • "results": [
    ]
}

Get connection utilization data

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/{:start,:end,:resolution}
Response samples
application/json
{
  • "connectionId": 120391239323,
  • "results": [
    ],
  • "unit": "Mbps"
}