REST Data Protocol Handler

The REST data protocol handler analyzes HTTP requests that follow the REST architectural style. The data protocol identifies the dynamic parts of the URI strings. The result is a set of rules. During the playback phase, the virtual service environment (lvse) uses the rules to virtualize HTTP requests that invoke the same operations.
dts101
The REST data protocol handler analyzes HTTP requests that follow the REST architectural style. The data protocol identifies the dynamic parts of the URI strings. The result is a set of rules. During the playback phase, the virtual service environment (
VSE
) uses the rules to virtualize HTTP requests that invoke the same operations.
If the 
VSE
 does not automatically select the REST data protocol, you can select it manually on the data protocol configuration page of the VS recorder, VS creator from RR or spec, and VS editor.
The following graphic shows the REST data protocol configuration UI as it appears in the VS editor.
REST DPH Settings.png
You can include the HTTP requests in live traffic or in request/response pairs.
You must use the HTTP/S transport protocol for request/response pairs.
You can configure some aspects of the analysis process.
Each rule contains one or more parameters, which represent the dynamic parts. By default, the parameters begin with the text
URLPARAM
.
The following sample rules include the parameters
URLPARAM0
and
URLPARAM1
. The parameters must be inside curly brackets in the rule. After the analyzer generates the rule, you can change the
URLPARAM
identifier.
GET /Service/rest/user/{URLPARAM0}
GET /Service/rest/customer/{URLPARAM0}
GET /Service/rest/customer/{URLPARAM0}/order/{URLPARAM1}
At playback, the following URI strings match the first rule:
GET /Service/rest/user/100
GET /Service/rest/user/101
At playback, the following URI string matches the third rule:
GET /Service/rest/customer/1234/order/5678
Parameters can also be mixed with other constant text if necessary. For example:
GET /Service/rest/user/{USERNAME}/format.{type}
In this example, the last token could be
format.json
or
format.xml
.
There can be any number of parameters in a token in any position. For example:
GET /Service/rest/users/format.{type}.sortorder.{order}.filter.{filter}
You can use the REST rules editor that appears after a recording to add or modify rules to look like this depending on your requirements. Rules like this can also be generated from WADL or RAML files.
2
Request/Response Pair Format
This section describes the format of request/response pairs for the REST data protocol.
Request
The request file must include a valid HTTP header. The URL is the first line of the header. The other header lines are optional.
The REST data protocol handler supports all the HTTP methods/verbs: GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, CONNECT, and PATCH.
The format of the URL line is:
<METHOD><a space character><REST API path><space><HTTP-VERSION>
For example:
PUT /rest-example/control/users/save HTTP/1.1
If the request includes a body, separate the body from the header with a blank line.
The following example shows a request that contains a body in JSON format.
PUT /rest-example/control/users/save HTTP/1.1
accept: application/json
content-Type: application/json
Connection: Keep-Alive
User-Agent: LISA
 
   {
     "user": {
       "emailAddress": "[email protected]",
       "firstName": "first-9",
       "lastName": "last-9",
       "password": "aaaaaaaa",
       "username": "dmxxx-009"
     }
   }
You can condense the JSON or XML body on a single line.
{ "user": { "emailAddress": "[email protected]","firstName": "first-9", "lastName": "last-9", "password": "aaaaaaaa", "username": "dmxxx-009"  }}
Response
The response file contains an HTTP response code. The file can contain a header and a body. The response code must be the first line in the file, in the following format:
<HTTP-VERSION><a space character><HTTP-RESPONSE-CODE>
The following example shows a response that has a body.
HTTP/1.1 200
 
"user":{"emailAddress":"[email protected]","firstName":"lisa",
"lastName":"simpson","password":"60fAFoq+W0R4HrLgsfPodkWRw9I=",
"phoneNumber":"","username":"lisa_simpson"}}
If the response does not include a response code line, the response code defaults to
200 (OK)
.
Rules Review and Modification
The
Virtual Service Image Recorder
, the
Virtual Service from request/response pairs
interface, and the
Configure
page in the VS editor include a page where you can review and modify the rules that the REST data protocol created.
The left panel (
URI Rules
) displays the rules. When you select a rule, the middle panel (
Matching Traffic
) displays a sample of traffic that matches the rule. To configure the maximum number of rows that display, set the
lisa.protocol.rest.editor.observedtraffic.max
property in the
lisa.properties
file.
REST DPH Service Configuration Tab.png
To display a list of HTTP requests that do not match the rules, click
Unmatched Traffic
. This list is empty if the rules match all the collected traffic. To configure the maximum number of requests that display, set the
lisa.protocol.rest.editor.unmatchedtraffic.max
property in the
lisa.properties
file.
REST DPH Unmatched Traffic.png
The URI Rules pane lets you add, update, reorder, and delete the rules.
You can replace the parameters in the rules with more meaningful names. For example:
GET /Service/rest/customer/{customerid}/order/{orderid}
You can create multiple rules that match the same operation. The rules are matched in the order shown. As a result, a rule that is higher in the list can match when you expect a lower rule to match. To change the order, use the reordering buttons. You can reorder rules, but when they are reloaded, they honor ordering per verb. This is done to ensure a more efficient way of handling matching. For performance considerations, GET rules are considered before DELETE rules because they are more common.
If you delete a rule, click
Unmatched Traffic
to see the effect of removing the rule on the captured traffic.
To change the values of the following configuration properties, open the
Analyzer Properties
panel in the top right.
REST DPH Analyzer Properties.png
If you have modified the REST URL rules, and then want to revert to the automatically generated URL rules, you can perform re analysis of the traffic. Click Properties, and when the Properties page displays, click OK without changing any values.
  • Max Changes
    Defines the maximum number of changes that are allowed for a token before the variability is considered significant enough to generate a rule.
    Think of a URI as a list of "tokens" separated by the "/" character. For example, the URI "GET /rest/user/1234" contains the tokens:
    • GET
    • rest
    • user
    • 1234
    To change the default value, set the
    lisa.protocol.rest.maxChanges
    property in the
    lisa.properties
    file.
  • Start Position
    Defines the position in the URL at which the REST data protocol starts looking for variable tokens.
    The start position is the index of a token in the list of tokens of which a URI is composed. For example, in the URI:
    GET /service/rest/customers"
    "GET" is at position 0 and "customers" is at position 3.
    To change the default value, set the
    lisa.protocol.rest.startPosition
    property in the
    lisa.properties
    file.
  • Id Identification Regular Expression
    Defines a regular expression string that the REST data protocol uses to detect resource identifiers in the HTTP requests. To change the default value, set the
    lisa.protocol.rest.idPattern
    property in the
    lisa.properties
    file.
  • URL Parameter Prefix
    Defines the prefix that the REST data protocol uses for the parameters in rules.
    The purpose of this setting is to help the analyzer spot tokens that follow a specific pattern that you know is variable, but which the analyzer may not automatically detect.
    For example, in the URI:
    GET /rest/user/person-1234-dev
    You may know that a user ID in the format
    person-nnnn-nnn
    always follows "user". In this case, you can define a regular expression to detect this pattern directly. In this example, the regular expression would be:
    person-[0-9]{4}-[a-z]{3}
    To change the default value, set the
    lisa.protocol.rest.parameterBaseName
    property in the
    lisa.properties
    file.
If you change one or more values for these properties, the data protocol reanalyzes the recorded traffic.