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:
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.
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
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.
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" }
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" }
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" }
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" }
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.
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" }
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" }
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" } }
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.
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" }
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" }
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" }
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.
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" }
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" }
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" } }
The following table list a few of the possible error codes you may come across:
Error Code | Description |
---|---|
403 | Forbidden. May occur if...
|
404 | Page not found. Invalid URL. |
500 | Internal server error. May occur if the requested operation is not supported. |