REST category

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 15 minutes to read

    • Verify the functionality of REST calls.

    Send REST Request - Inbound - REST API Explorer

    This test step begins with the REST API Explorer. Use the REST API Explorer to create and specify the HTTP method, path, query parameters, request headers, and body of a REST request, and then send the REST request to the current instance.

    When you have tested the request, the Create Automated Test Step button appears. Click Create Automated Test Step to create the test step. This button does not appear until after the request has been sent. You cannot create a test step when the request payload is larger than the maximum request payload size property.

    This test step creates the same test record as the Send REST Request - Inbound test step. After the test step is created, you cannot go back and use the REST API Explorer to update the test. All changes must be made on the Send REST Request - Inbound test step form.

    No HTTP response validation is performed as part of this step. The step fails if the response payload size is too big, the request parameters are invalid, or the request could not be sent. Use the assert steps to validate the response.

    You cannot use this step to send a request to another instance or third party/remote address.

    These inputs are for the REST API Explorer. The fields you see depend upon the API selected. For more information on using REST APIs on your instance, see REST APIs.

    Table 1. Inputs
    Field Description
    Namespace Namespace for the request. Select from the list.
    API Name API to be used. Select from the list.
    API Version API version to be used. Select the version available on your instance from the list.
    Path parameters The part of the path after the API name. Path parameters are generally name-value pairs where the allowable values are in a list.
    Query parameters Name-value pairs of query parameters added to the URI after the path.

    The REST API Explorer encodes the URI, so it is not necessary to encode query parameters and values.
    Request headers Name-value pairs contained in the request header. The authentication header is set to Send as me to use the current user's credentials. To use the test step in production, you may need to change the Basic Authentication field in the Send REST - Inboundtest step.

    Do not encode the name or value.
    Request Body The request content. Some requests do not have a body.

    Send REST Request - Inbound

    Create a test step to send a REST request to the current instance. Specify the HTTP method, path, query parameters, request headers, and body of a REST request.

    No HTTP response validation is performed as part of this step. The step fails if the response payload size is too big, the request parameters are invalid, or the request could not be sent. Use the assert steps to validate the response.

    You cannot use this step to send a request to another instance or third party/remote address.

    For more information on using REST APIs, see the REST APIs.

    Table 2. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Basic authentication If you are using a public API, you do not need to provide authentication credentials.

    If you are using a non-public API, you must provide the basic authentication information when doing the test. If you leave this field blank, you may receive unexpected results. For example, the response-status code might be 401 Unauthorized instead of 200 OK.

    You must create or select a basic authentication profile to assign to test steps to avoid authentication issues when running the test.

    Users must have the web_service_admin role to fully leverage the REST test steps. Without this role, users cannot view or set basic authentication profiles needed for endpoints that require authentication. Without this role, users can still leverage the REST test steps for public APIs and unauthenticated access to non-public APIs. For full REST test step access, the atf_ws_designer role is available and contains the web_service_admin role along with the atf_test_designer role.
    Method The HTTP method to be used:
    • GET
    • POST
    • PUT
    • DELETE
    • PATCH
    Path The path to be used. This field accepts only the portion of the URI after the instance name. If you use https://<instance name>, you get an error.
    Query Parameters Query parameter names and values. Do not encode the parameter names or values.
    Headers Header names and values. Do not encode the header names or values.
    Body The body of the request.

    Assert Status Code

    Assert that the HTTP response status code has the specified relationship to the specified value. You specify a numeric value of the status code and the relationship.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 3. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Operation Comparison to be performed between values:
    • is
    • is not
    • less than
    • greater than
    • less than or is
    • greater than or is
    Status code Status code to be tested against the response code.

    Assert Status Code Name

    Assert that the HTTP response status code name has the specified relationship to the specified value. You specify a value of the status code name, and the relationship.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 4. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Operation Comparison to be performed between values:
    • contains
    • does not contain
    • is
    • is not
    Status code name Status code name to be tested.

    Assert Response Time

    Assert that the HTTP response time has the specified relationship to the specified value. You specify a value of the response time and the relationship.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 5. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Operation Comparison to be performed between Response time entered and actual response time:
    • less than
    • greater than
    Response time (ms) Time in milliseconds to be compared to the actual response time.

    Assert Response Header

    Assert the HTTP response header exists, or the header has the specified relationship to the specified value.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 6. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Header Header name.
    Operation Comparison to be performed between values:
    • contains
    • does not contain
    • is
    • is not
    • is not empty
    Value Element value to be used in the test. Not shown if the Operation is is not empty.

    Assert Response JSON Payload is Valid

    Assert that the response payload is in valid JSON format.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 7. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.

    Assert Response XML Payload is Well-Formed

    Assert that the response payload is well-formed XML.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 8. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.

    Assert XML Payload Element

    Assert the XML response payload element exists, or has the specified relationship to the specified value.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 9. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Element path XML path to the element to be evaluated. For example, /result/short_description for
    {
  "result": {
    "number": "INC0020001",
    "short_description": "test"
  }
}
    Operation Comparison to be performed between values:
    • contains
    • does not contain
    • is
    • is not
    • is not empty
    Value Element value to be used in the test. Not shown if the Operation is is not empty.

    Assert JSON Response Payload Element

    Assert the JSON response payload element exists, or has the specified relationship to the specified value.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Table 10. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Element path SNC path to the element to be evaluated. For example, /result/short_description for
    {
  "result": {
    "number": "INC0020001",
    "short_description": "test"
  }
}
    See Importing JSON files for more information.
    Operation Comparison to be performed between values:
    • contains
    • does not contain
    • is
    • is not
    • is not empty
    Value Element value to be used in the test. Not shown if the Operation is is not empty.

    Assert Response Payload

    Assert the HTTP response payload has the specified relationship to the specified value. You specify the value and the relationship.

    Assert steps must immediately follow a Send REST Request - Inbound step. You can have multiple REST assert steps following a Send REST Request - Inbound step, but the assert steps cannot be separated from the Send REST Request - Inbound step by steps from other test categories.

    Note:
    The entire payload is used to look for a match. A large payload can affect performance.
    Table 11. Inputs
    Field Description
    Execution order Integer specifying the order in which the test executes this step.

    As you create steps, the system automatically assigns each step an incremental value. This value causes the test to execute steps in the order that you created them in. You can change this default order by editing the Execution order values.
    Active Option to activate this test step for use.
    Application Application scope in which the system runs this step.
    Test Read-only name of the test that you're adding the step to.
    Step config Read-only name of the step.
    Description Description of the test step. This field value is automatically set based on the field values of the test step. This field appears after the test step is submitted.
    Notes Notes about the test step.
    Operation Comparison to be performed between values:
    • contains
    • does not contain
    • is
    • is not
    • is not empty
    Response body The value of the response body to be used in the test.

    Must contain the name and value to be compared as it appears in the response payload. Must not contain any curly braces.

    Not shown if the Operation is is not empty.
    To check the short description in the response payload
    {"result":{"number":"INC0010040","short_description":"Test ATF Incident"}}
    the Response body should contain
    "short_description":"Test ATF Incident"
    These formats are incorrect and the step fails.
    • {"short_description":"Test ATF Incident"}
    • "{"short_description":"Test ATF Incident"}"
    • short_description: Test ATF Incident
    • short_description:"Test ATF Incident"