API for UI Users
Creating and Editing Virtual Locations
Creating and editing virtual locations in the UI requires three steps as described below.
To create or edit a virtual location from the UI:
-
Set Location: this API call should be executed before opening the UI; the input for this API is an object containing the following sub-objects.
-
newLocationData: represents a new location and contains these parameters:
- id: the virtual locations ID (optional). If the parameter is not passed, the ID will be generated by the Location Editor and returned in the response
- name: the virtual locations name (mandatory).
- description: a description for the virtual locations (optional).
-
existingLocation: represents an existing location; contains the locationMetadata of a previously created location.
Note: Only newLocationData or existingLocation should be included.
-
globalConfig: this object represents the global configurations which refer to all locations, see Editing Global Configurations. This object is passed when editing a location for display only. It can't be changed while editing a location.
Note: For the Location's Capture Packets option to be configurable in the GUI, the Global Configuration object (globalConfig) must be included, and the Global Capture Packets parameter within it (isCaptureClientPl) must be set to "True".
The API returns an ID which is used in Step 2 to open the UI and later to get the edited virtual location object.
-
-
Open the Location Editor GUI with the following URL:
http://ip:port/shunra/locationeditor?tempdirid=<id from step 1>&readonly=<true/false>
Query parameters:
- tempdirid: the ID that was received in Step 1.
- readonly: indicates whether the GUI will be editable or read only.
-
Finish editing: After the edit is finished and "OK/Cancel" is clicked, the UI calls the javascript function "locationEditCompleted" which is expected to be part of the opener of the UI, see Public JavaScript API for UI Openers. This function should call another API "Finish editing" which clears all data related to edited location and returns the result of the edit – the new location.
Query parameter:
tempDirId: the ID returned in the "setLocation" API.
Request
JSON
URL | http://ip:port/shunra/api/locationeditor/location |
HTTP Method | POST |
HTTP Headers |
Content-Type: application/json Accept: application/json Authorization: See Web Services Authentication. |
Body (New Location) | { "newLocationData": { id: "76c29fc2538d4de7a9a839bc18dc6b4f", name: "location name", description: "location description" }, "existingLocation": null, "globalConfig": { "settings": { "isCaptureClientPl": false, "packetListMaxSizeMB": 300, "isPacketListCaptureCyclic": false }, "excludeIps": [{ "from": "172.30.2.150", "to": "172.30.2.150", "protocol": 0, "port": 0 }] } } |
Body (Existing Location) | { "newLocationData": null, "existingLocation": { "srcIp": null, "destIp": null, "srcIpRange": null, "destIpRange": { "include": [], "exclude": [] }, "id": "76c29fc2538d4de7a9a839bc18dc6b4f", "name": "location name", "type": "CUSTOM", "description": "location description", "ntx": null, "selectedFlow": null, "latency": 113, "packetloss": 0.1, "bandwidthIn": 2000.0, "bandwidthOut": 1000.0, "isCaptureClientPl": false, "sharedBandwidth": true, "ntxMetadata": null, "glMetadata": null }, "globalConfig": { "settings": { "isCaptureClientPl": false, "packetListMaxSizeMB": 300, "isPacketListCaptureCyclic": false }, "excludeIps": [{ "from": "172.30.2.150", "to": "172.30.2.150", "protocol": 0, "port": 0 }] } } |
XML
URL | http://ip:port/shunra/api/locationeditor/location |
HTTP Method | POST |
HTTP Headers |
Content-Type: application/xml Accept: application/xml Authorization: See Web Services Authentication. |
Body (New Location) | <locationData> <newLocationData> <id>76c29fc2538d4de7a9a839bc18dc6b4f</id> <name>location name</name> </newLocationData> <globalConfig> <settings> <isCaptureClientPl>false</isCaptureClientPl> <packetListMaxSizeMB>300</packetListMaxSizeMB> <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic> </settings> <excludeIps> <From>172.30.2.51</From> <To>172.30.2.51</To> <Protocol>0</Protocol> <Port>0</Port> </excludeIps> </globalConfig> </locationData> |
Body (Existing Location) | <locationData> <existingLocation> <destIpRange> <exclude> <from>172.30.2.50</from> <to>172.30.2.50</to> <port>0</port> <protocol>0</protocol> </exclude> </destIpRange> <id>76c29fc2538d4de7a9a839bc18dc6b4f</id> <name>new location</name> <type>CUSTOM</type> <latency>113</latency> <packetloss>0.1</packetloss> <bandwidthIn>2000.0</bandwidthIn> <bandwidthOut>1000.0</bandwidthOut> <isCaptureClientPl>false</isCaptureClientPl> <sharedBandwidth>true</sharedBandwidth> </existingLocation> <globalConfig> <settings> <isCaptureClientPl>false</isCaptureClientPl> <packetListMaxSizeMB>300</packetListMaxSizeMB> <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic> </settings> <excludeIps> <From>172.30.2.51</From> <To>172.30.2.51</To> <Protocol>0</Protocol> <Port>0</Port> </excludeIps> </globalConfig> </locationData> |
Response
JSON
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/json; charset=UTF-8 |
HTTP Body | { error: null, errorCode: 0, data: "76c29fc2538d4de7a9a839bc18dc6b4f" } |
XML
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/xml; charset=UTF-8 |
HTTP Body | <error /> <errorCode>0</errorCode> <data>76c29fc2538d4de7a9a839bc18dc6b4f</data> |
Request
JSON
URL | http://ip:port/shunra/api/locationeditor/location/{tempDirId} |
HTTP Method | DELETE |
HTTP Headers |
Content-Type: application/json Accept: application/json Authorization: See Web Services Authentication. |
Body | None |
XML
URL | http://ip:port/shunra/api/locationeditor/location/{tempDirId} |
HTTP Method | DELETE |
HTTP Headers |
Content-Type: application/xml Accept: application/xml Authorization: See Web Services Authentication. |
Body | None |
Response
JSON
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/json; charset=UTF-8 |
HTTP Body | { "error": null, "errorCode": 0, "data": { "id": "76c29fc2538d4de7a9a839bc18dc6b4f", "locationMetadata": { "srcIp": null, "destIp": null, "srcIpRange": null, "destIpRange": { "include": [], "exclude": [{ "from": "172.30.2.50", "to": "172.30.2.50", "port": 0, "protocol": 0 }] }, "id": "76c29fc2538d4de7a9a839bc18dc6b4f", "name": "new location", "type": "CUSTOM", "description": null, "ntx": null, "selectedFlow": null, "latency": 113, "packetloss": 0.1, "bandwidthIn": 2000.0, "bandwidthOut": 1000.0, "isCaptureClientPl": false, "sharedBandwidth": true, "ntxMetadata": null, "glMetadata": null } } } |
XML
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/xml; charset=UTF-8 |
HTTP Body | <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <serverResponse> <errorCode>0</errorCode> <data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="generatedLocation"> <id>76c29fc2538d4de7a9a839bc18dc6b4f</id> <locationMetadata> <destIpRange> <exclude> <from>172.30.2.50</from> <to>172.30.2.50</to> <port>0</port> <protocol>0</protocol> </exclude> </destIpRange> <id>76c29fc2538d4de7a9a839bc18dc6b4f</id> <name>new location</name> <type>CUSTOM</type> <latency>113</latency> <packetloss>0.1</packetloss> <bandwidthIn>2000.0</bandwidthIn> <bandwidthOut>1000.0</bandwidthOut> <isCaptureClientPl>false</isCaptureClientPl> <sharedBandwidth>true</sharedBandwidth> </locationMetadata> </data> </serverResponse> |
Editing Global Configurations
Global Configurations are configurations which affects all the tests running on Network Virtualization.
Editing the Global Configurations in the UI requires three steps as described below.
To edit the Global Configuration from the UI:
-
Set Configuration: This API should be called before opening the UI. The request body can be either empty for creating a new Global Configurations object, or contain the "data" of a Global Configurations object previously created for editing it.
It returns an ID which is used in Step 2 to open the GUI and later to get the edited Global Configuration object.
-
Open the Configuration Editor GUI with the following URL:
http://ip:port/shunra/configeditor?tempdirid=<id from step 1>&readonly=<true/false>
Query parameters:
- tempdirid: the id that was received in Step 1.
- readonly: indicates whether the GUI will be editable or read only.
-
Finish Editing: After the editing is comleted and "OK/Cancel" is clicked, the UI calls a javascript function " configurationEditCompleted " which is expected to be part of the opener of the UI, see Public JavaScript API for UI Openers. This function should call another API "Finish editing" which clears all data related to edited configuration and returns the result of the edit – the new configuration object. Query parameter:
tempDirId: the ID that was returned in "Set Configuration"
Request
JSON
URL | http://ip:port/shunra/api/locationeditor/config |
HTTP Method | POST |
HTTP Headers |
Content-Type: application/json Accept: application/json Authorization: See Web Services Authentication. |
Body (New Configuration) | None |
Body (Existing Configuration) | { "isCaptureClientPl": false, "packetListMaxSizeMB": 300, "isPacketListCaptureCyclic": true, "excludeIps": [{ "from": "172.30.2.150", "to": "172.30.2.150", "protocol": 0, "port": 0 }] } |
XML
URL | http://ip:port/shunra/api/locationeditor/config |
HTTP Method | POST |
HTTP Headers |
Content-Type: application/xml Accept: application/xml Authorization: See Web Services Authentication. |
Body (New Configuration) | None |
Body (Existing Configuration) | <?xml version="1.0" encoding="UTF-8" ?> <configuration> <settings> <isCaptureClientPl>false</isCaptureClientPl> <packetListMaxSizeMB>300</packetListMaxSizeMB> <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic> </settings> <excludeIps> <From>172.30.2.50</From> <To>172.30.2.50</To>F <Protocol>0</Protocol> <Port>0</Port> </excludeIps> </configuration> |
Response
JSON
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/json; charset=UTF-8 |
HTTP Body | { error: null, errorCode: 0, data: "76c29fc2538d4de7a9a839bc18dc6b4f" } |
XML
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/xml; charset=UTF-8 |
HTTP Body | <error /> <errorCode>0</errorCode> <data>81f64d6bc97f4430b9165772197835c7</data> |
Finish Edit Configuration Examples
Request
JSON
URL | http://ip:port/shunra/api/locationeditor/config/{tempDirId} |
HTTP Method | DELETE |
HTTP Headers |
Content-Type: application/json Accept: application/json Authorization: See Web Services Authentication. |
Body | None |
XML
URL | http://ip:port/shunra/api/locationeditor/config/{tempDirId} |
HTTP Method | DELETE |
HTTP Headers |
Content-Type: application/xml Accept: application/xml Authorization: See Web Services Authentication. |
Body | None |
Response
JSON
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/json; charset=UTF-8 |
HTTP Body | { "error": null, "errorCode": 0, "data": { "settings": { "isCaptureClientPl": false, "packetListMaxSizeMB": 300, "isPacketListCaptureCyclic": false }, "excludeIps": [{ "from": "172.30.2.150", "to": "172.30.2.150", "protocol": 0, "port": 0 }] } } |
XML
HTTP Response Code | 200 - OK |
HTTP Headers | Content-Type: application/xml; charset=UTF-8 |
HTTP Body | <?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <serverResponse> <errorCode>0</errorCode> <data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="configuration"> <settings> <isCaptureClientPl>false</isCaptureClientPl> <packetListMaxSizeMB>300</packetListMaxSizeMB> <isPacketListCaptureCyclic>false</isPacketListCaptureCyclic> </settings> <excludeIps> <From>172.30.2.50</From> <To>172.30.2.50</To> <Protocol>0</Protocol> <Port>0</Port> </excludeIps> </data> </serverResponse> |
Using the Global Configuration Object
The configuration parameters stored in the global configuration object can be used for the Set Configuration for Location Based Emulation.
The Global Packet Capture parameter "isCaptureClientPl" should be passed in the Location Based Mode Start Test request; refer to Start Test, Location Based Mode.
Note: Starting a test with "isCaptureClientPl" set to False will stop the Packet capture for all users.
Public JavaScript API for UI Openers
The "Openers" of the UIs should implement the following API in javascript:
-
configurationEditCompleted(okClicked): for Configuration Editor opener
- okClicked: is a boolean indicating whether the Configuration Editor was closed by clicking the "OK" button or the editing was canceled ("cancel" button).
- Is called after the editor is closed.
-
locationEditCompleted(okClicked): for Location Editor opener
- okClicked: is a boolean indicating whether the Location Editor was closed by clicking the "OK" button or the editing was canceled ("cancel" button).
- Is called after the editor is closed.