Circuit

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The Circuit endpoint provides the API consumer with access to methods pertaining to circuits and related data objects. The endpoint allows consumers to create and update circuits, retreive circuit information, and link circuits to various other data objects.

Methods

URL base/Circuits/Circuit/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Circuit controller.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
 {
 "HttpAction": "Get",
 "MethodName": "GetCircuitByCircuitID",
 "Description": "Returns the record for a single Circuit given the passed in ID value (see Path).",
 "Path": "/Circuit/GetCircuitByCircuitID/25032"
 },
 {
 "HttpAction": "Get",
 "MethodName": "GetCircuitByDescription",
 "Description": "Returns the record for a single Circuit given the passed in Description value.",
 "Path": "/Circuit/GetCircuitByDescription/25032"
 },
 {
 "HttpAction": "Get",
 "MethodName": "GetCircuitsByCustomerNetworkID",
 "Description": "Returns the record(s) for one or more Circuits given the passed in CustomerNetworkID value.",
 "Path": "/Circuit/GetCircuitsByCustomerNetworkID/25032"
 },
 {
 "HttpAction": "Get",
 "MethodName": "GetCircuitsByCustomerID",
 "Description": "Returns the record(s) for one or more Circuits given the passed in CustomerID value.",
 "Path": "/Circuit/GetCircuitsByCustomerID/25032"
 },
 {
 "HttpAction": "Get",
 "MethodName": "GetCircuitsByTicketID",
 "Description": "Returns the record(s) for one or more Circuits given the passed in TicketID value.",
 "Path": "/Circuit/GetCircuitsByTicketID/25032"
 },
 {
 "HttpAction": "Get",
 "MethodName": "GetSubCircuitsByID",
 "Description": "Returns the hierarchy of circuits given the passed in parent Circuit ID value.",
 "Path": "/Circuit/GetSubCircuitsByID/25032"
 },
 {
 "HttpAction": "Post",
 "MethodName": "AddCircuit",
 "Description": "Adds a circuit given the passed in Circuit object",
 "Format": {
 "Description": "Sample comments or description",
 "Billable": false,
 "Priority": 50,
 "Size": 123,
 "Alias": "Sample alias",
 "Status": 1
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "UpdateCircuit",
 "Description": "Updates a circuit given the passed in Circuit object",
 "Format": {
 "ID": 45,
 "Description": "Sample comments or description",
 "Billable": false,
 "Priority": 50,
 "Size": 123,
 "Alias": "Sample alias",
 "Status": 1
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "DeleteCircuit",
 "Description": "Deletes a circuit given the passed in Circuit ID",
 "Format": {
 "ID": 45
 }
 },
  {
 "HttpAction": "Post",
 "MethodName": "LinkCircuitToCustomer",
 "Description": "Links a circuit to a customer given the IDs of both",
 "Format": {
 "CircuitID": 123,
 "CustomerID": 456
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "UnlinkCircuitToCustomer",
 "Description": "Unlinks a circuit to a customer given the IDs of both",
 "Format": {
 "CircuitID": 123,
 "CustomerID": 456
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "LinkCircuitToCustomerNetwork",
 "Description": "Links a circuit to a customer network given the IDs of both",
 "Format": {
 "CircuitID": 123,
 "CustomerNetworkID": 456
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "UnlinkCircuitToCustomerNetwork",
 "Description": "Unlinks a circuit to a customer network given the IDs of both",
 "Format": {
 "CircuitID": 123,
 "CustomerNetworkID": 456
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "LinkSubCircuit",
 "Description": "Links a circuit to a sub circuit given the IDs of both",
 "Format": {
 "ParentCircuitID": 111,
 "SubCircuitID": 222
 }
 },
 {
 "HttpAction": "Post",
 "MethodName": "UnlinkSubCircuit",
 "Description": "Unlinks a circuit to a sub circuit given the IDs of both",
 "Format": {
 "ParentCircuitID": 111,
 "SubCircuitID": 222
 }
 }
]
URL base/Circuits/Circuit/AddCircuit
Action POST
Description Returns the Circuit object just added to the M4 database.
Parameters
Name Required? Type Description
Description Yes String The description of the circuit. Must be unique.
Billable No Boolean Designates whether the circuit is billable.
Priority No Integer The priority of the circuit (1-100).
Size No Integer The ID corresponding to the CircuitSize entry.
Alias No String The alias given to the circuit.
Status No Integer The ID corresponding to the CircuitStatus entry.
Sample JSON Package 
{
      "Description": "Circuit-2",
      "Billable": false,
      "Priority": 88,
      "Size": 1,
      "Alias": "VZN.842684.1667\\r\\nLVL3/324/016/DE",
      "Status": 1
}
Returns A JSON Circuit data object
Sample Return Object 
{
 "Description": "Circuit123",
 "Billable": false,
 "Priority": 88,
 "Size": 1,
 "Alias": "Alias123",
 "Status": 1,
 "ID": 352200
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • Description: Must be unique
  • Priority: Must be an integer between 1 and 100.
  • Size: This value must exist as an ID to the CircuitSize object.
  • Status: This value must exist as an ID to the CircuitStatus object.
URL base/Circuits/Circuit/UpdateCircuit
Action POST
Description Returns the Circuit object just updated in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the circuit in the M4 Database.
Description Yes String The description of the circuit. Must be unique.
Billable No Boolean Designates whether the circuit is billable.
Priority No Integer The priority of the circuit (1-100).
Size No Integer The ID corresponding to the CircuitSize entry.
Alias No String The alias given to the circuit.
Status No Integer The ID corresponding to the CircuitStatus entry.
Sample JSON Package 
{
 "ID": 12345
 "Description": "Sample comments or description",
 "Billable": false,
 "Priority": 50,
 "Size": 123,
 "Alias": "Sample alias",
 "Status": 1
 }
Returns A JSON Circuit data object
Sample Return Object 
{
 "Description": "Circuit123",
 "Billable": false,
 "Priority": 88,
 "Size": 1,
 "Alias": "Alias123",
 "Status": 1,
 "ID": 352200
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ID: Must exist as an ID in the Circuit object.
  • Description: Must be unique
  • Priority: Must be an integer between 1 and 100.
  • Size: This value must exist as an ID to the CircuitSize object.
  • Status: This value must exist as an ID to the CircuitStatus object.
URL base/Circuits/Circuit/DeleteCircuit
Action POST
Description Returns the Circuit object just updated in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the circuit in the M4 Database.
Sample JSON Package 
{
 "ID": 12345
 }
Returns A JSON Circuit data object
Sample Return Object 
{
 "Message": "The circuit with ID [12345] was deleted successfully."
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ID: Must exist as an ID in the Circuit object.
  • Existence of sub-circuits: Circuit must not have any linked sub-circuits.
URL base/Circuits/Circuit/GetCircuit/ID
Action GET
Description Returns a Circuit object when given an ID of a valid circuit in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a circuit in the M4 database.
Returns A JSON Circuit data object
Sample Return Object 
{
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
}
URL base/Circuits/Circuit/GetCircuitByDescription
Action POST
Description Returns a Circuit object when given a description of a valid circuit in the M4 database.
Parameters
Name Required? Type Description
Description Yes String A string value representing the description of a circuit in the M4 database.
Sample JSON Package 
{
      "Description": "1st Fiberless Ring Circuit"
}
Returns A JSON Circuit data object
Sample Return Object 
{
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
}
URL base/Circuits/Circuit/GetCircuitsByTicketID/ID
Action GET
Description Returns a list of Circuit objects when given a ticketID is attached in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer A integer value representing the ticketID attached to a circuit in the M4 database.
Returns A JSON collection of Circuit data objects
Sample Return Object 
[
 {
 "Description": "SyncTest",
 "Billable": true,
 "Priority": 1,
 "Size": 8,
 "Alias": "",
 "Status": null,
 "ID": 2
 },
 {
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
 }
]
URL base/Circuits/Circuit/GetSubCircuitsByID/ID
Action GET
Description Returns a list of SubCircuit IDs when given a circuitID is attached in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer A integer value representing the circuitID attached to a circuit in the M4 database.
Returns A JSON object containing the CircuitID and a collection of SubCircuit IDs
Sample Return Object 
{
 "CircuitID": 8,
 "SubCircuits": {
 "SubCircuitIDs": []
 }
}
URL base/Circuits/Circuit/GetCircuitsByCustomerID/ID
Action GET
Description Returns a list of Circuit objects when given a customerID is attached in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer A integer value representing the customerID attached to a circuit in the M4 database.
Returns A JSON collection of Circuit data objects
Sample Return Object 
[
 {
 "Description": "SyncTest",
 "Billable": true,
 "Priority": 1,
 "Size": 8,
 "Alias": "",
 "Status": null,
 "ID": 2
 },
 {
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
 }
]
URL base/Circuits/Circuit/GetCircuitsByCustomerNetworkID/ID
Action GET
Description Returns a list of Circuit objects when given a customerNetworkID is attached in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer A integer value representing the customerNetworkID attached to a circuit in the M4 database.
Returns A JSON collection of Circuit data objects
Sample Return Object 
[
 {
 "Description": "SyncTest",
 "Billable": true,
 "Priority": 1,
 "Size": 8,
 "Alias": "",
 "Status": null,
 "ID": 2
 },
 {
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
 }
]
URL base/Circuits/Circuit/LinkCircuitToCustomerNetwork
Action POST
Description Links a circuit to a customer network in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer The ID of the circuit in the M4 Database.
CustomerNetworkID Yes Integer The ID of the customer network in the M4 Database.
Sample JSON Package 
{
 "CircuitID": 3,
 "CustomerNetworkID": 1
}
Returns A JSON response message.
Sample Return Object 
{
 "CircuitID": 3,
 "CustomerNetworkID": 1
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CircuitID: Must exist as an ID on a Circuit object.
  • CustomerNetworkID: Must exist as an ID on a CustomerNetwork object.
URL base/Circuits/Circuit/UnlinkCircuitFromCustomerNetwork
Action POST
Description Unlinks a circuit from a customer network in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer The ID of the circuit in the M4 Database.
CustomerNetworkID Yes Integer The ID of the customer network in the M4 Database.
Sample JSON Package 
{
 "CircuitID": 3,
 "CustomerNetworkID": 1
}
Returns A JSON response message.
Sample Return Object 
{
 "CircuitID": 3,
 "CustomerNetworkID": 1
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CircuitID: Must exist as an ID on a Circuit object.
  • CustomerNetworkID: Must exist as an ID on a CustomerNetwork object
URL base/Circuits/Circuit/LinkSubCircuit
Action POST
Description Links a circuit to a sub circuit in the M4 database.
Parameters
Name Required? Type Description
ParentCircuitID Yes Integer The ID of the parent circuit in the M4 Database.
SubCircuitID Yes Integer The ID of the sub circuit in the M4 Database.
Sample JSON Package 
{
 "ParentCircuitID": 8,
 "SubCircuitID": 32
}
Returns A JSON response message.
Sample Return Object 
{
 "ParentCircuitID": 8,
 "SubCircuitID": 32
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ParentCircuitID: Must exist as an ID on a Circuit object.
  • SubCircuitID: Must exist as an ID on a Circuit object.
  • Circuits not already linked.
  • Parent circuit must have an associated fiber channel.
URL base/Circuits/Circuit/UnlinkSubCircuit
Action POST
Description Unlinks a circuit from a sub circuit in the M4 database.
Parameters
Name Required? Type Description
ParentCircuitID Yes Integer The ID of the parent circuit in the M4 Database.
SubCircuitID Yes Integer The ID of the sub circuit in the M4 Database.
Sample JSON Package 
{
 "ParentCircuitID": 8,
 "SubCircuitID": 32
}
Returns A JSON response message.
Sample Return Object 
{
 "ParentCircuitID": 8,
 "SubCircuitID": 32
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ParentCircuitID: Must exist as an ID on a Circuit object.
  • SubCircuitID: Must exist as an ID on a Circuit object.
  • Circuits currently linked.
  • Parent circuit must have an associated fiber channel.
URL base/Circuits/Circuit/LinkCircuitToCustomer
Action POST
Description Links a circuit to a customer in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer The ID of the circuit in the M4 Database.
CustomerID Yes Integer The ID of the customer in the M4 Database.
Sample JSON Package 
{
 "CircuitID": 3,
 "CustomerID": 1
}
Returns A JSON response message.
Sample Return Object 
{
 "CircuitID": 3,
 "CustomerID": 1
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CircuitID: Must exist as an ID on a Circuit object.
  • CustomerID: Must exist as an ID on a Customer object.
URL base/Circuits/Circuit/UnlinkCircuitFromCustomer
Action POST
Description Unlinks a circuit from a customer in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer The ID of the circuit in the M4 Database.
CustomerID Yes Integer The ID of the customer in the M4 Database.
Sample JSON Package 
{
 "CircuitID": 3,
 "CustomerID": 1
}
Returns A JSON response message.
Sample Return Object 
{
 "CircuitID": 3,
 "CustomerID": 1
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CircuitID: Must exist as an ID on a Circuit object.
  • CustomerID: Must exist as an ID on a Customer object
URL base/Circuits/Circuit/LinkCircuitToCircuit
Action POST
Description Links a circuit to another circuit in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer The ID of a circuit in the M4 Database.
LinkedCircuitID Yes Integer The ID of a circuit in the M4 Database.
Sample JSON Package 
{
 "CircuitID": 8,
 "LinkedCircuitID": 32
}
Returns A JSON response message.
Sample Return Object 
{
 "CircuitID": 8,
 "LinkedCircuitID": 32
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CircuitID: Must exist as an ID on a Circuit object.
  • LinkedCircuitID: Must exist as an ID on a Circuit object.
  • Circuits not already linked.
  • Both circuits must have associated fiber channels.
URL base/Circuits/Circuit/UnlinkCircuitFromCircuit
Action POST
Description Unlinks a circuit from another circuit in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer The ID of a circuit in the M4 Database.
LinkedCircuitID Yes Integer The ID of a circuit in the M4 Database.
Sample JSON Package 
{
 "CircuitID": 8,
 "LinkedCircuitID": 32
}
Returns A JSON response message.
Sample Return Object 
{
 "CircuitID": 8,
 "LinkedCircuitID": 32
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • CircuitID: Must exist as an ID on a Circuit object.
  • LinkedCircuitID: Must exist as an ID on a Circuit object.
  • Circuits must already be linked.
URL base/Circuits/Circuit/GetLinkedCircuitsByCircuit/CircuitID
Action GET
Description Returns a list of Circuit objects linked to a CircuitID in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer A integer value representing the ID of a circuit in the M4 database.
Returns A JSON collection of Circuit data objects
Sample Return Object 
[
 {
 "Description": "SyncTest",
 "Billable": true,
 "Priority": 1,
 "Size": 8,
 "Alias": "",
 "Status": null,
 "ID": 2
 },
 {
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
 }
]
URL base/Circuits/Circuit/GetCircuitsByEquipmentDescription
Action POST
Description Returns a Circuit object when given a description of a valid circuit in the M4 database.
Parameters
Name Required? Type Description
Description Yes String A string value representing the description of equipment in the M4 database.
Sample JSON Package 
{
      "Description": "X-42 Card 17"
}
Returns A JSON Circuit data object
Sample Return Object 
[{
 "Description": "1st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 3
},{
 "Description": "21st Fiberless Ring Circuit",
 "Billable": false,
 "Priority": 1,
 "Size": 19,
 "Alias": "",
 "Status": null,
 "ID": 77
}]
URL base/Circuits/Circuit/GetEquipmentByCircuit/CircuitID
Action GET
Description Returns a list of Network Equipment objects linked to a CircuitID in the M4 database.
Parameters
Name Required? Type Description
CircuitID Yes Integer A integer value representing the ID of a circuit in the M4 database.
Returns A JSON collection of Network Equipment data objects
Sample Return Object 
[
 {
 "LinkTable": "Bay",
 "LinkDBKey": 232,
 "Description": "Sample Bay Description"
 },
 {
 "LinkTable": "Card",
 "LinkDBKey": 232,
 "Description": "Sample Card Description"
 },
 {
 "LinkTable": "Shelf",
 "LinkDBKey": 230,
 "Description": "Sample ShelfDescription"
 },
]

Was this article helpful?

Yes No

Related Articles