Help_Topics

Web Service Settings

The Web Service Settings area is broken up into several sections, each containing related settings. A section on the Settings page can be expanded and collapsed by clicking on either the section's title or the triangle to the left of the title.

Variables Defined for this Service

This section displays the variables that have been defined for use throughout the rest of the Web Service request. The example below shows two variables defined for this particular service:

Once created, defined variables can be used anywhere in the request. For example, to use the variable named SECRET_KEY, simply include the text <VAR SECRET_KEY> in any text field or text area on the page. At runtime, the monitoring engine will replace <VAR SECRET_KEY> with the value of the variable. For example, to use the value of variable SECRET_KEY in the web service location field, one would type:

To define variables:

  1. Click the Edit Variables link. This will open the Edit Variables for this Request pop-up window:
  2. Fill in the appropriate text fields for each variable type. Click the Add link if more variables of a particular type are required.
  3. Click OK to close the pop-up window and save your changes to the Defined Variables section. Click Cancel to close the pop-up window and ignore any edits that you have made.
  4. To remove a variable, click the to the right of the corresponding variable's text fields.

Variable Types

  1. Constant Variables
    • Constant variables retain the value they have been provided throughout the request.
  2. Date/Time Variables
    • Date/Time variables allow for the specification of current timestamps that may be needed when generating web service requests. For a full reference of all the parameters that can be used in the Format field of these variables, please see the standard UNIX strftime reference.
    • Important: the Format field of Date/Time variables always expects the formatting directives to be enclosed in double quotes("). For example, to set a Date/Time variable to the current number of epoch seconds in the UTC time zone, you would fill in:
  3. Mathematical Variables
    • Mathematical variables can be used to compute values dynamically. Their operands can be either numeric or can reference other defined variables. For example, to add 120 to the epoch seconds defined by the TIME_STAMP variable defined above, you would fill in:
  4. Encrypted Variables
    • Encrypted variables can be used to monitor web services which require request authentication. Currently, MD5, HMACSHA1, HMACMD5 and SHA1_HEX based authentication is supported.
      • For each algorithm, the resulting hash is encoded as follows:
        HMAC_SHA1 base64
        HMACMD5 base64
        MD5 hexadecimal
        SHA1_HEX hexadecimal
      • To define a variable whose value is hashed with the HMACSHA1 algorithm, fill in all the text fields as shown below:
      • To define a variable whose value is hashed with the HMACMD5 algorithm, fill in all the text fields as shown below:
      • To define a variable whose value is hashed with the MD5 algorithm, fill in the Variable Name and Value to Encrypt text fields. MD5 hashes do not use the Key field:
      • To define a variable whose value is hashed with the SHA1_HEX algorithm, fill in the Variable Name and Value to Encrypt text fields. SHA1_HEX hashes do not use the Key field.

Web Service Parameters

This section allows for the specification of request parameters, as outlined below.

Web Service Location

The location to which the request message will be delivered. This is usually a URI, such as http://s3.amazonaws.com:80/soap.

Web Service Type

SOAP

  • A standard defined by the W3C. SOAP request messages conform to the W3C standard. SOAP messages are composed of a SOAP-Envelope containing an optional SOAP-Header element and a mandatory SOAP-Body element. SOAP messages are formatted as XML, so both the request message and the response message will be formatted as XML.
  • Selecting SOAP from the web service type drop down will cause the following HTTP Headers to be added to the web service parameters:
    Header Name Initial Value
    SOAPAction empty
    Content-Type text/xml; charset=utf-8
    • These headers are usually required by SOAP web services. If these headers do not apply to your particular web service request, simply remove them.

REST

  • An acronym for REpresentational State Transfer. REST is a subset of web service types that include those which transmit messages over HTTP without additional messaging layers or session tracking. REST web services are often accessed by encoding the request in the URL and using the GET transport method. Although the request message is often times not XML, the response from a REST web service will be XML.

HTML/Text

  • HTML/Text web services do not comply with either the SOAP or REST paradigm and may use custom GET/POST requests as well as custom response formatting.
Transport Method

POST

  • A method of sending data to the web service over HTTP whereby the data being sent will appear within a message body. Headers sent with a post request also contain additional values such as Content-Length. POST does not have the character limit which some browsers impose on the GET transport method. POST is often considered more secure as the data being transported is hidden from the user.

GET

Transport Payload

Name/Value Pairs

  • When performing GET requests, this option may be a useful alternative to entering the complete URL in the web service location text field. This option allows the user to quickly see exactly which parameters are set to which value. For example, if a user wants to request http://domain/webservice?parameter1=value1&parameter2=value2, the user can:
    • Specify http://domain/webservice as the Web Service Location
    • Enter parameter1 and parameter2 in the fields located directly under Parameter Name and entering value1 and value2 in the fields directly under Parameter Value, as shown below:

XML Message to POST

  • This subsection will be available when the transport method is set to POST and the web service type is set to SOAP. The XML message to be sent to the web service is shown here, as seen below:
  • To edit the XML message:
    1. Click on the Edit XML Message link, and the XML message editor will be shown:
    2. Type or paste the XML message into the text box
    3. Click OK to save your edits back to the Transport Payload subsection or Cancel to discard them
    4. This text box is often used to specify the entire SOAP request to be sent to a SOAP web service.

Formdata to POST

  • This subsection will be available when the transport method is set to POST and the web service type is set to REST or HTML/TEXT.
  • It works in the same manner as the XML Message to POST subsection described above. Instead of specifying an XML message to post you may specify formdata to be posted with the request, such as parameter name/value pairs. An example of formdata that may be entered is:
    • username=test1&password=secretkey&action=login
Transport Options

Disable Redirects

  • This check box allows for the disabling of HTTP redirects. Certain web services may send back an HTTP redirect. By default, HTTP redirects are enabled and will be followed. Checking the Disable Redirects check box will stop the web services monitor from following any HTTP redirects.

Disable HTML Encoding

  • This check box allows for disabling the HTML encoding of the request. By default, characters such as '=' or ' ' are encoded to their HTML equivalents. If this box is checked, the monitoring engine will assume the user has provided all request elements already encoded in HTML-safe characters and will send the request to the server as-is.
HTTP Headers
  • Allows for the specification of arbitrary HTTP Headers. Enter header name and values as shown below:
  • IMPORTANT: The User-Agent header is added and set to blank by default. If it is not present when you click "Save Settings" or "Save & Test Settings" it will be added by the system. This ensures no user agent header is sent as part of the web service request. Should a user agent header be required, simply set the value of the header to the desired one.

Response Verification

This section allows for the specification of conditions the web service response must comply to. If the response meets the conditions, the request is logged as a success. If the response does not meet the conditions, the request is logged as an error.

Verify Keyword

Keyword to check the response for in order to declare the request a success. If the verify keyword is not found in the server response, the request is recorded as a content error.

Error Keyword

If this keyword is found in the server response, the request is recorded as a content error.

To secure sensitive data

  1. Plese review the Security_Best_Practices guide
  2. Follow the instructions provided by the Utility to Secure Sensitive Data

See also

Dynamically_test_your_site_with_an_Instacheck
Set_up_Baseline_Agents
Specify_monitoring_agents
Web_Service_Transaction_Settings