HTTP Methods

In this section:

Objects in the system are represented as resources that are identified using a logical URI. The URI, along with the HTTP method, identify the resource and the operation performed by the server. All REST services are stateless, which means that the request must contain enough state to answer the request.

Users can send requests to read, create, modify and delete objects on the DSC Platform. Not all operations are necessarily supported. For example, some objects (or a subset of their attributes) are read-only. The request to delete such object will result in error. Also, only TL1-supported attributes can be returned. The response of the REST API contains a response status code and text of response body to indicate success or failure of the request.

The REST API operations are invoked by sending in one of the HTTP methods (verbs). The following table lists the REST API operations with the corresponding HTTP method and TL1 command:

REST API Operations

HTTP Methods	Descriptions	TL1
GET	Retrieve (read) data	VFY
POST	Create a new object	ADD
PUT	Edit object's attributes	CHG
PUT	Apply action to an object	SET
DELETE	Delete an object	DLT

In the following sections, the format examples all use cURL command line tool. In these examples, the username and password should be replaced with your own username and password. Similarly, the {{service_ip}} and {{service_port}} should be replaced with the system's IP address and port number.

Before Using HTTP Methods

In the SNMP Configuration tab on Web UI, the DSC REST API attribute must be enabled in order for the requests to be processed (see Authentication). If the DSC REST API is not enabled, the following response code and message may be displayed:

Request:

curl -k -u username:password -X GET \
 https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA

Response:

Response status code: 403
Response body:
Forbidden: REST API is disabled

GET

The GET (read) request allows you to read information about an object identified by the request URI. The DSC responds with response status code 200 if the GET request has been successfully processed.

GET Example 1: Reading DREs from the MTP3 Application

Request:

curl -k -u username:password -X GET \
 https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/1/DREs/DRE

Response:

Response status code: 200
Response body:
{
  "results": {
    "1-1": {
      "CLLI": "Slot 1",
      "IPAddress1": "slot1_0",
      "IPAddress2": "",
      "State": "AVAILABLE"
    },
    "1-2": {
      "CLLI": "Slot 2",
      "IPAddress1": "slot2_0",
      "IPAddress2": "",
      "State": "AVAILABLE"
    }
  },
  "status": "success"
}

GET Example 2: Reading Routesets in MTP3 NA 9 and STANDARD Routeset List

Request:

curl -k -u username:password -X GET \
 https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/9/RoutesetList/STANDARD/Routeset

Response:

Response status code: 200
Response body:
{
  "results": {
    "9-STANDARD-5.009.1-MEMBER": {
      "Alarms": "ENABLED",
      "AllowXRoutesets": "DISABLED",
      "BroadcastTCA": "ENABLED",
      "BroadcastTCP": "ENABLED",
      "BroadcastTCR": "ENABLED",
      "BroadcastTFA": "ENABLED",
      "BroadcastTFP": "ENABLED",
      "BroadcastTFR": "ENABLED",
      "CLLI": "N/A",
      "CongestionLevel": "FALSE",
      "CongestionNotifOfUPs": "8",
      "DestinationState": "INACCESSIBLE",
      "LoadshareMode": "NODE_VALUE",
      "RESTAttrCount": 16,
      "RoutesetID": "UNDEFINED",
      "RoutesetState": "ACTIVE",
      "TestState": "IDLE"
    }
  },
  "status": "success"
}

GET Example 3: Reading VNodes in the MTP3 NA 90

In the following example, the MTP3 NA 90 does not have VNodes associated with it. In this case, the REST API will reject the GET request and respond with an error message.

Request:

curl -k -u username:password -X GET \
 https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/VNodes/VNode

Response:

Response status code: 500
Response body:
{
  "results": {
    "message": "object VNode(90) is not found",
    "tag": "operation-failed",
    "urlpath": "/api/defMTP/MTP3NAManager/MTP3NA/90/VNodes/VNode"
  },
  "status": "failure"
}

GET Example 4: Unauthorized Reading

In the following example, the client request has invalid credentials (wrongusername:wrongpassword). In this situation, the REST API will not authorize the request and deny access to the DSC.

Request:

curl -k -u wrongusername:wrongpassword -X GET \
 https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA

Response:

Response status code: 403
Response body:
{
  "results": {
    "message": "TL1 authentication error",
    "tag": "access-denied",
    "urlpath": "/api/defMTP/MTP3NAManager/MTP3NA"
  },
  "status": "failure"
}

POST

A POST (create) request is used to create a new object in the DSC (for example, a linkset). When issuing a POST request, the request body must contain attributes required for the object's creation. The DSC responds with status code 200 if the POST request has been successfully created.

POST Example 1: Creating a VNode in MTP3 NA 87

Request:

curl -k -u username:password -X POST \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/87/VNodes/VNode \
  -H 'content-type: application/json' \
  -d '{"VPC": "001.002.006"}'

Response:

Response status code: 200
Response body:
{
  "results": {},
  "status": "success"
}

Confirmation using GET request:

Request:
curl -k -u username:password -X GET \
 https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/87/VNodes/VNode/001.002.006
Response status code: 200
Response body:
{
  "results": {
    "87-001.002.006": {
      "BroadcastTFA": "ENABLED",
      "BroadcastTFP": "ENABLED",
      "BroadcastTFR": "ENABLED",
      "CLLI": "",
      "Context": "VNODE 001.002.006",
      "Description": "",
      "MateSTPDistribution": "ENABLED",
      "State": "ACTIVE"
    }
  },
  "status": "success"
}

Post Example 2: Creating a L2Connection in MTP3 NA 90

Request:

curl -k -u username:password -X POST \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/L2Connections/L2Connection \
  -H 'content-type: application/json' \
  -d '{"CageID": "1", "DREID": "1", "Type": "SCTP", "MTP2ProtocolType": "PROPRIETARY"}'

Response:

Response status code: 200
Response body:
{
  "results": {},
  "status": "success"
}

Confirmation using GET request:

Request:
curl -k -u username:password -X GET \
https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/L2Connections/L2Connection/1,1,SCTP,PROPRIETARY
Response status code: 200
Response body:
{
  "results": {
    "90-1-1-SCTP-PROPRIETARY": {
      "AssociationNumber": "-1",
      "Bundling": "ENABLED",
      "BundlingTO": "20",
      "CageID": "1",
      "CageName": "",
      "Checksum": "CRC32C",
      "CommandRetry": "10000 ms",
      "CommandTimeout": "1000 ms",
      "ConnectionRetry": "5000 ms",
      "ConnectionTimeout": "60000 ms",
      "Context": "L2C TDM D1 C1",
      "DREID": "1",
      "DelayedACKTO": "20",
      "FastRetransThreshold": "4",
      "Heartbeat": "ENABLED",
      "HeartbeatInterval": "150",
      "LocalIPAddress1": "",
      "LocalIPAddress2": "",
      "LocalPort": "25490",
      "M2UAVariant": "GENERIC",
      "MTP2ProtocolType": "PROPRIETARY",
      "MTP2ProtocolVersion": "-1",
      "MaximumAssocRetrans": "15",
      "MaximumPathRetrans": "10",
      "RTOInitial": "180",
      "RTOMaximum": "250",
      "RTOMinimum": "180",
      "RemoteIPAddress1": "",
      "RemoteIPAddress2": "",
      "RemotePort": "4055",
      "SCTPDebugLevel": "0",
      "State": "INACTIVE",
      "Type": "SCTP"
    }
  },
  "status": "success"
}

POST Example 3: An attempt to create an object with duplicate key

In the following example, NA 91 in MTP3 already exists. When a request tries to create a duplicate, the REST API will reject the POST request and return an error message.

Request:

curl -k -u username:password -X POST \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA \
  -H 'content-type: application/json' \
  -d '{'NetworkAppearance': '91'}'

Response:

Response status code: 500
Response body:
{
  "status": "failure",
  "results": {
    "urlpath": "/api/defMTP/MTP3NAManager/MTP3NA",
    "message": "request: [[[add/NA/91]]], response: [[[('DENIED,IPNV', ['\\t:\"Duplicate network appearance\";'])]]]",
    "tag": "operation-failed"
  }
}

PUT

The PUT (edit/set) request is used to update an object in the DSC or execute an action, such as activation. When issuing a PUT request, the body of the request should contain editable attributes and their new values. As in the case of TL1, some objects may require deactivation before an attribute can be modified. The request to perform a specific action is conveyed by setting "perform<ActionName>" to "True" in the request body. The DSC responds with status code 200 if the PUT request has been successfully processed.

PUT Example 1: Activation of inactive VNode 001.002.006 in MTP3 NA 90

Request:

curl -k -u username:password -X PUT \
  https://{service_ip}:{service_port}/api/defMTP/MTP3NAManager/MTP3NA/90/VNodes/VNode/001.002.006 \
  -H 'content-type: application/json' \
  -d '{"performActivate": "True"}'

Response:

Response code: 200

Response body: 
{
  "results": {},
  "status": "success"
}

Confirmation using GET request:

Request:
curl -k -u username:password -X GET \
  https://{{service_ip}}:{{service_host}}/api/defMTP/MTP3NAManager/MTP3NA/90/VNodes/VNode/001.002.006
Response status code: 200
Response body:
{
  "results": {
    "90-001.002.006": {
      "BroadcastTFA": "ENABLED",
      "BroadcastTFP": "ENABLED",
      "BroadcastTFR": "ENABLED",
      "CLLI": "",
      "Context": "VNODE 001.002.006",
      "Description": "TEST",
      "MateSTPDistribution": "ENABLED",
      "State": "ACTIVE"
    }
  },
  "status": "success"
}

Put Example 2: Modifying Remote IPs in the M2PALink

Request:

curl -k -u username:password -X PUT \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/Linksets/Linkset/001.002.008/M2PALink/1 \
  -H 'content-type: application/json' \
  -d '{"RemoteIPAddress1": "localhost", "RemoteIPAddress2": "localhost"}'

Response:

Response code: 200

Response body: 
{
  "results": {},
  "status": "success"
}

Confirmation using GET request:

Request:
curl -k -u username:password -X GET \
  https://{{service_ip}}:{{service_post}}/api/defMTP/MTP3NAManager/MTP3NA/90/Linksets/Linkset/001.002.008/M2PALink/1
Response code: 200
Response body: 
{
  "results": {
    "90-001.002.008-1": {
      "APC": "001.002.008",
      "Alarms": "ENABLED",
      "Bundling": "ENABLED",
      "BundlingTO": "20",
      "Checksum": "CRC32C",
      "CongestionLevel": "FALSE",
      "Context": "001.002.008-01",
      "DREID": "3",
      "DataDebugLevel": "1",
      "DataLinkBandwidth": "64",
      "DelayedACKTO": "20",
      "DiagnosticMessage": "Configured",
      "FastRetransThreshold": "4",
      "GR310VirtualLink": "DISABLED",
      "Heartbeat": "ENABLED",
      "HeartbeatInterval": "150",
      "L2State": "NOT_INITIALIZED",
      "L3State": "DEACTIVATED",
      "LinkName": "001.002.008-01",
      "LinksetSCTPValues": "YES",
      "LocalIPAddress1": "",
      "LocalIPAddress2": "",
      "LocalPort": "0",
      "M2PAVersion": "RFC 4165",
      "MaximumAssocRetrans": "15",
      "MaximumPathRetrans": "10",
      "ProtocolDebugLevel": "10",
      "RTOInitial": "180",
      "RTOMaximum": "250",
      "RTOMinimum": "180",
      "RXAbatementBusy": "9900000",
      "RXOnsetBusy": "10000000",
      "RemoteIPAddress1": "localhost",
      "RemoteIPAddress2": "localhost",
      "RemotePort": "0",
      "RxMSUCount": "0",
      "SCTPDebugLevel": "1",
      "SLC": "1",
      "SendINIT": "ENABLED",
      "SoftwareDebugLevel": "1",
      "TXAbatementL1": "30 %",
      "TXAbatementL2": "50 %",
      "TXAbatementL3": "70 %",
      "TXOnsetL1": "40 %",
      "TXOnsetL2": "60 %",
      "TXOnsetL3": "80 %",
      "TXQueueSize": "3000000",
      "TxMSUCount": "0",
      "UserActivated": "DISABLED"
    }
  },
  "status": "success"
}

Put Example 3: Resetting a route in MTP3 NA 90

Request:

curl -k -u username:password -X PUT \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/RoutesetList/STANDARD/Routeset/001.002.004,MEMBER/Route/001.002.008 \
  -H 'content-type: application/json' \
  -d '{"performResetState": "True"}'

Response:

Response code: 200
Response body: 
{
  "results": {},
  "status": "success"
}

DELETE

The DELETE request is used to delete a resource. The DELETE request uses the URI query string to delete the appropriate object. The DSC responds with status code 200 if the DELETE request has been successfully deleted.

Delete Example 1: Deleting Route 001.002.008

Request format:

curl -k -u username:password -X DELETE \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/RoutesetList/STANDARD/Routeset/001.002.004,MEMBER/Route/001.002.008

Response:

Response status code: 200

Response body:
{
  "results": {},
  "status": "success"
}

Delete Example 2: Deleting DRE 3

Request:

curl -k -u username:password -X DELETE \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/1/DREs/DRE/3

Response:

Response status code: 200
Response body:
{
  "results": {},
  "status": "success"
}

Delete Example 3: Deleting an object which requires deactivation before deletion

In the following example, the initial state of VNode is "ACTIVE". Since a VNode must first be deactivated before being deleted, the REST API will reject the DELETE request and return an error message.

Request:

curl -k -u username:password -X DELETE \
  https://{{service_ip}}:{{service_port}}/api/defMTP/MTP3NAManager/MTP3NA/90/VNodes/VNode/001.002.006

Response:

Response status code: 500
Response body: 
{
  "status": "failure",
  "results": {
    "urlpath": "/api/defMTP/MTP3NAManager/MTP3NA/90/VNodes/VNode/001.002.006",
    "message": "request: [[[dlt/VND/90-001.002.006]]], response: [[[('DENIED,SESW', ['\\t:\"Cannot remove an active VNode - deactivate first.\";'])]]]",
    "tag": "operation-failed"
  }
}

Error Codes

The following table list a few of the possible error codes you may come across:

REST API Error Codes

Error Code	Description
403	Forbidden. May occur if... DSC REST API flag is disabled. TL1 can not authenticate a request based on the username/password provided.
404	Page not found. Invalid URL.
500	Internal server error. May occur if the requested operation is not supported.

Space shortcuts

Page tree

Before Using HTTP Methods

GET

GET Example 1: Reading DREs from the MTP3 Application

GET Example 2: Reading Routesets in MTP3 NA 9 and STANDARD Routeset List

GET Example 3: Reading VNodes in the MTP3 NA 90

GET Example 4: Unauthorized Reading

POST

POST Example 1: Creating a VNode in MTP3 NA 87

Post Example 2: Creating a L2Connection in MTP3 NA 90

POST Example 3: An attempt to create an object with duplicate key

PUT

PUT Example 1: Activation of inactive VNode 001.002.006 in MTP3 NA 90

Put Example 2: Modifying Remote IPs in the M2PALink

Put Example 3: Resetting a route in MTP3 NA 90

DELETE

Delete Example 1: Deleting Route 001.002.008

Delete Example 2: Deleting DRE 3

Delete Example 3: Deleting an object which requires deactivation before deletion

Error Codes