RestApiTester: A Java-based REST API Testing Utility

Overview

• RestApiTester is a Java-based utility designed to facilitate the testing of REST APIs. It accepts the input in the form of JSON files (either a single JSON file or a folder having multiple JSON files), processes them to create the APIs dynamically, sends HTTP requests, and validates the responses against predefined criteria.

• For each input JSON file, the utility logs the output in three formats: (to provide comprehensive feedback for developers and testers)

  1. console logs

  2. <input-file-name>_api_test_results_<TIMESTAMP>.log file: Human-readable test log

  3. <input-file-name>_api_test_results_<TIMESTAMP>.json file: Structured JSON report

• Given its focus on REST API testing, it is particularly valuable for ensuring endpoint reliability and performance in software development projects.

Execution Flow

• API_HOST_NAME: It will fetch the API_HOST_NAME dynamically, allowing to run the same input test files in different environments (i.e. DEV / QA / STAGE / UAT, etc..)

• Reading and Parsing Input: It will read the input JSON file(s) to create the API requests dynamically. (variable: INPUT_JSON_PATH, value: path to a single JSON file or a folder having multiple JSON files)

• Initialize Log Files: It will clear the previous *.log and *.json files if exist and will initialize a new *.log and *.json files for each input JSON file.

• Comprehensive Logging: It captures logs in three formats—console output, *.log files, and *.json reports—to ensure detailed analysis.

• Testing Each Endpoint: Send the API requests dynamically and validate the API response against expected results to detect inconsistencies.

• Finalize Api Test Results: Finalize the API test results files to provide detailed information on each API test and its outcome.

Configuration

The utility provides different configuration options that enhance its usability and effectiveness:

1. API_HOST_NAME
   - HostName where the API testing should take place.
   - Must be an environment variable.
   - It’s kind of an entry point for the RestApiTester. So, if found as null/empty, the utility will exist and will log the failure in the console.
   - Example: export API_HOST_NAME=http://localhost:8080

2. INPUT_JSON_PATH
   - Path to the single input JSON file or a folder having multiple input JSON file(s).
   - It can be either a command-line argument (highest preference) or an environment variable. If not, the utility will fetch the default value from the application.properties file.
   - Even after verifying all the 3 options (mentioned above), if found as null/empty, the utility will exist and will log the failure in the console.
   - Example: export INPUT_JSON_PATH=src/main/resources

3. LOG_API_TEST_RESULTS
   - An environment variable
   - To indicate whether we need to log only FAILURES or ALL the API test results to the *.log and *.json files.
   - Default Value: ALL
   - Possible values: ALL, FAILURE_ONLY
   - Example: export LOG_API_TEST_RESULTS=ALL

Chain Endpoints

What Are Chain Endpoints?

Chain endpoints are dependent API tests that dynamically use data from a parent API's response to construct their own requests. They enable testing workflows where:

1. The output of one API becomes the input of another.

2. Multi-step scenarios (e.g., fetch a resource, validate its metadata, then fetch linked resources).

Key Characteristics

• Dependency: Executed only if the parent API test succeeds.

• Dynamic Parameters: Use FETCH to extract values from parent responses.

• Hierarchical: Chains can have sub-chains (e.g., Chain 1 → Chain 1.1 → Chain 1.1.1).

(We will discuss Chain Endpoints in detail in the next chapter i.e. API Testing Features)

Key Features

• Method Support: It can handle GET and POST HTTP methods for now.

• Response Validation: Ideally, the API JSON response can either be an Object or an Array. It will validate the JSON response against the expectedStatusCode, expectedNumberOfRecords and expectedAttributes. If the API is returning an array, the default behavior is that all the objects will be validated against the expectedAttributes; while the utility also allows an option to define the specific objects (from an array) to be validated against the expectedAttributes.

• Recursive Testing:

  • If the Primary API is returning an array as a response; then for all the objects (of array), the chain API calls will be triggered.

  • If the Chain API is trying to FETCH an attribute from the Primary API response which is an array, the Chain API calls will be triggered for all the elements of an array.
    (Both scenarios will be explained in detail in the next chapter i.e. API Testing Features)

• Scalability: Supports single and batch API testing to handle diverse testing needs.

• Performance & Reliability Testing: Helps ensure API endpoints are stable and performant.

• Data Verification: Ensures the required data is available (can be used after a data load)

Build the Project

GIT: https://bitbucket.org/dxtera/osid-api-tester/src/master/
RestApiTester: https://bitbucket.org/dxtera/osid-api-tester/src/master/src/main/java/org/dxtera/osid/api/tester/RestApiTester.java
Perform 'clean' and 'build' using gradle.

Run the RestApiTester

There are multiple ways to run it.
Input can be either a JSON file or a directory having multiple JSON files.

1. With command-line arguments. (Absolute or Relative path both will work.)

• Gradle command - provide the input json file

• Java -jar command (provide the input json file as an argument)

2. With environment variable.

• Gradle command - export the input json file

• Java -jar command (export the input json file)

3. With default arguments. (code will read it from the application.properties file)

• Gradle command

• Java -jar command

4. Run the RestApiTester application.

• It will take the default arguments from the application.properties file. It's a preferable approach for active development.

ToDo: Storage for input JSON files

• There is an ongoing discussion about options for storing the input JSON files per school.

  • Google Drive (Highly Recommended)

  • A separate repository

  • osid-api-tester

  • ??

• The input JSON files used by RestApiTester may be updated frequently by a school to add or modify test scenarios. Hence, better to maintain the versioning of input JSON files such as storing version 1, version 2, and so on at Google Drive. Based on the configuration provided, the RestApiTester dynamically picks up the specific version of input files per school, executes the corresponding test scenarios, and processes them accordingly, ensuring seamless and up-to-date API testing.