Using the RESTful API

dsTest provides a RESTful API to aid in your automated testing. Your automation tool or scripts may communicate directly with dsTest through JSON/HTTP 1.1 rather than using dsClient Terminal and parsing textual responses or using XML/TCP. You can use dsClient Terminal, however, to convert your existing XML configurations to JSON. See Working with JSON Configurations for more information on that as well as tips on creating a JSON configuration and creating a collection you can import into Postman. If desired, you can enable HTTPS rather than using HTTP.

The formatting used to display JSON in this topic is purely for readability. White space in JSON text is neither required nor a violation and you can choose to condense the text or to add white space as you prefer.

Request Messages

The base URI for the RESTful API is /dsTest_v1/ and the complete URI depends on the type and purpose of a request message. Port 10002 is used for this traffic. Therefore, your messages must use the following URL:

http://<dsTest host>:10002/dsTest_v1/

The syntax used to address element values, attributes, and attribute values in a URI is the same as the syntax used with dsClient Terminal.

Methods

The method that you define in your request message determines the operation that dsTest will attempt. The URIs in those messages generally identify either a structure or an operation while the message body contains the data to provision the structure or to define the operation.

Unlike XML documents, the RESTful API requires that configuration structures and commands be conveyed with different types of messages as described below.

POST

The sole purpose of a POST request is to load a configuration. That being the case, the devsol and config elements are assumed. The URL for a POST request identifies the root of the structure to be loaded. You can think of the URL as the path to the member to be provisioned and the message body as the member's value as shown in the examples below.

If you are interested in utilization tracking, you can provision the from header in your request messages with an identifier that dsTest will associate with the test for utilization notifications just as it does with your user name when you load a test using dsClient Desktop.

Load only node configurations:

URI: /dsTest_v1/nodes
Message body: {          "spr":{<configuration>},
          "mme":{<configuration>}} 

Load only alias configurations:

URI: /dsTest_v1/aliases
Message body: {          ["host":{<configuration>}, "host":{<configuration>}],
          ["interface":{<configuration>}, "interface":{<configuration>}]}

Load a traffic profile:

URI: /dsTest_v1/traffic_profile
Message body: {[          "rate_point":{<configuration>},
          "rate_point":{<configuration>},
          "rate_point":{<configuration>},
          "rate_point":{<configuration>}]}

Load all three of the above structures with one request:

URI: /dsTest_v1/
Message body: {          "aliases":{<configuration>},
          "traffic_profile":{<configuration>},
          "nodes":{<configuration>}}

GET

GET requests are used to perform simple query or executable commands. In this case the devsol and command elements are assumed and the first element in the URI would be a child of command. In this context a "simple" command is defined as a linear, descending path to a single element that is qualified by no more than one attribute. Commands that require more than one attribute or more than one child element, diag om measurement queries or action commands respectively for example, must use the PUT method since a message body will also be required. dsTest will respond to successful queries with a JSON object containing the result.

Query a subscriber value:

Note that the use of :<instance name> was not necessary with hss since its instance name was also "hss" or with subscriber_database since our path started with the node associated with the database.

URI: /dsTest_v1/hss/subscriber_database/subscriber_group:start:1/dynamic_information/mme_identity
Response: { "mme_identity":"client.developingsolutions.com"}

Query the status of existing nodes:

URI: /dsTest_v1/nodes/status
Response: { "hss": {           "@name":"hss",
          "status": {          "started":"true",
                    "ready":"true",
                    "active":"false",
                    "interfaces_connected":"1",
                    "test_name":"Local Library/4G Testing/simple_hss_s6.dsx",
                    "user_name":"devsol"}}}

Register for status change notifications (see Server Notifications for more information regarding registrations with REST):

URI: /dsTest_v1/register:type:status_change
Response: empty unless an error is returned

Retrieve queued notifications of all registered types:

URI: /dsTest_v1/notifications
Response: [          {          "type":"status_change",
                    "message":"hss - hss - Started Occurred:Fri Oct 18 14:26:13:423452"},
          {          "type":"status_change",
                    "message":"hss - hss - Ready Occurred:Fri Oct 18 14:26:25:186086"},
          {          "type":"status_change",
                    "message":"DiameterPeer - client.developingsolutions.com - Diameter Peer Open Occurred:Fri Oct 18 14:26:25:186097"},
          {          "type":"status_change",
                    "message":"mme - mme_1 - Ready Occurred:Fri Oct 18 14:26:25:186166"},
          {          "type":"status_change",
                    "message":"DiameterPeer - server.developingsolutions.com - Diameter Peer Open Occurred:Fri Oct 18 14:26:25:186177"}]

PUT

Use a PUT request to issue a complex query or executable command, or to modify a configured value. PUT requests include a message body that defines the command parameters or the value(s) to be modified. Here again the devsol and command elements are assumed and the first element in the URI must be a child of command. Only the response to a query command contains a message body unless an error is returned.

Modify a subscriber value (corresponds to the query example above):

URI: /dsTest_v1/hss/subscriber_database/subscriber_group:start:1/dynamic_information/
Message body: {"mme_identity":"client.developingsolutions.com"}

Query for error measurements from the last full interval (returns only the measurements that are greater than zero):

URI: /dsTest_v1/diag/om
Message body: {          "last":"true",
          "errors":"true",
          "all": ""}

Issue an action command:

URI: /dsTest_v1/hss/action
Message body: {          "@name":"insert_action",
          "rate":"10",
          "cycle":"1",
          "group":"4g_subs",
          "app":"s6",
          "event":"insert"}

Stop an action:

URI: /dsTest_v1/<node element name>[:<node instance name>]/action
Message body: {          "@name":"<action name>",
          "rate":"0"}

DELETE

DELETE requests, as the name suggests, are used to delete the node emulators or Traffic Profiles that were loaded with POST requests. A DELETE request has no message body - the URI identifies the resource to be deleted. dsTest deletes a Subscriber Database after the last node that references it is deleted.

URI: /dsTest_v1/<element name>[:<instance name>]

Status Codes

dsTest will return the following Status Codes under the stated conditions:

2XX: the request was successful.

400 Bad Request: the URI and/or message body was malformed. This error would equate to an XML validation error.

404 Not Found: the resource identified by the URI does not exist.