Rest Assured Java API Automation Learning Framework

Progressive Java API automation learning framework for SDET interview preparation, Rest Assured practice, framework design, and portfolio demonstration.

This repository starts with Java, HTTP, REST, JSON, Maven, TestNG, and Rest Assured foundations, then grows module by module into a mature API automation framework with reusable request specifications, endpoint constants, client and service layers, domain POJOs, Jackson mapping, data-driven testing, schema validation, safe diagnostics, WireMock, Allure, Extent, parallel smoke execution, and GitHub Actions CI.

The goal is not just to show a finished framework. The goal is to show how a framework evolves and why each layer exists.

This project is the Rest Assured/API automation companion to the Selenium Java SDET learning framework style: a linear, checkpointed repo where the learning journey is as important as the final code.

Modular Learning Structure

This repository is intentionally built as a linear learning path, not as a one-shot final framework.

Each module was developed on its own branch, completed, tagged, and then carried forward into main. That gives learners two useful ways to study the project:

Git Object	Purpose
module-XX-name branch	Shows the completed module checkpoint as a named learning branch.
module-XX-complete tag	Marks the exact commit where that module was completed.
main	Always points to the latest completed framework state.

Inspect the available checkpoints:

git branch --list 'module-*'
git tag --list 'module-*-complete' --sort=version:refname

Study the framework at a specific point:

git checkout module-04-complete
git checkout module-09-complete
git checkout module-16-complete
git checkout module-20-complete
git checkout main

When checking out a tag, Git enters detached HEAD mode. That is fine for reading and running tests. If you want to experiment from a checkpoint, create a practice branch:

git switch -c practice/module-13 module-13-complete

Compare two completed checkpoints:

git diff module-12-complete..module-13-complete

Recommended study flow for each module:

1. Read docs/module-XX-*/00-module-overview.md.
2. Review the module's focused concept docs.
3. Open the source files linked from the docs.
4. Run the module's verification commands.
5. Compare the checkpoint with the previous module.

The final framework matters, but the main learning value is seeing why each layer was introduced.

Learning Phases

Phase	Modules	Learning Goal
Java and API foundations	01-03	Learn Java syntax, HTTP/REST/JSON basics, Maven, TestNG, and Rest Assured setup.
Rest Assured request and response skills	04-08	Learn BDD/non-BDD syntax, request/response objects, assertions, extraction, CRUD, payloads, POJOs, Gson, and Jackson.
TestNG and API state	09-10	Learn lifecycle, groups, data providers, parameters, dependencies, authentication, tokens, cookies, and stateful flows.
Framework foundation	11-13	Add config, BaseApiTest, reusable request specs, endpoints, client/service layers, domain models, payload builders, and Jackson mapping.
Data and contracts	14-15	Add JSON/CSV/Excel data readers, TestNG data providers, schema validation, and contract boundaries.
Diagnostics and controlled failures	16-17	Add Log4j2, safe Rest Assured filters, sensitive-data masking, and WireMock-based controlled 404/500 tests.
Reporting and execution maturity	18-19	Add Allure results, Extent HTML reporting, class-level parallel smoke execution, GitHub Actions CI, and Jenkins notes.
Capstone and portfolio	20	Review final architecture, runbook, portfolio story, JUnit 5 comparison, and BDD/API testing appendix.

Module Checkpoints

Checkpoint	What The Project Contains
module-01-complete	Java classes, objects, methods, constructors, collections, control flow, and API automation vocabulary.
module-02-complete	HTTP, REST, resources, methods, status codes, headers, JSON, and API testing mental models.
module-03-complete	Maven project setup, TestNG lifecycle checks, Rest Assured dependency setup, and first environment verification tests.
module-04-complete	Rest Assured BDD-style given(), when(), then(), base URI, base path, query parameters, headers, logging, and simple body validation.
module-05-complete	Non-BDD Rest Assured objects: RequestSpecification, Response, and ValidatableResponse.
module-06-complete	Hamcrest body checks, TestNG assertions, AssertJ assertions, JSONPath extraction, headers, content type, and response time checks.
module-07-complete	Restful Booker CRUD tests with create, read, update, partial update, delete, and negative flows.
module-08-complete	Payload construction with raw JSON strings, maps, POJOs, Gson, and Jackson.
module-09-complete	TestNG lifecycle, priorities, groups, suite XML, data providers, parameters, and dependencies for API tests.
module-10-complete	Token creation, token extraction, cookie-authenticated protected operations, unauthorized checks, and stateful API flows.
module-11-complete	Framework config, environment reader, BaseApiTest, and reusable Restful Booker request specification.
module-12-complete	Endpoint constants, low-level API client, booking service layer, and framework-style service tests.
module-13-complete	Domain POJOs, auth models, create response model, booking payload builder, and centralized Jackson mapper.
module-14-complete	JSON, CSV, and Excel test data fixtures, readers, TestNG data providers, and data-driven framework tests.
module-15-complete	JSON schema files, schema path constants, and Rest Assured schema validation for booking responses.
module-16-complete	Log4j2-backed safe diagnostics, Rest Assured failure-focused filter, and sensitive-data masking.
module-17-complete	WireMock local stubs for deterministic 404 and 500 responses with safe diagnostic validation.
module-18-complete	Allure raw results, Extent HTML report, and TestNG listener-based reporting.
module-19-complete	Conservative class-level parallel smoke suite, GitHub Actions workflow, artifact upload, and Jenkins execution notes.
module-20-complete	Final architecture review, runbook, portfolio packaging, capstone checklist, JUnit 5 appendix, and BDD/API testing appendix.

Final Framework State

Area	Implementation
Language	Java 21
Build tool	Maven
API automation	Rest Assured
Test framework	TestNG
Primary live API	Restful Booker
Early/simple APIs	JSONPlaceholder and Zippopotam.us where useful
Assertions	Rest Assured/Hamcrest, TestNG, AssertJ
JSON mapping	Gson taught early, Jackson used as the final framework mapper
Test data	JSON, CSV, Excel with Apache POI
Contract testing	Rest Assured JSON schema validator
Mocking/stubbing	WireMock standalone
Diagnostics	Log4j2, Rest Assured filters, sensitive-data masking
Reports	Surefire, Allure raw results, Extent HTML report
Parallel execution	Conservative TestNG class-level smoke suite
CI	GitHub Actions workflow with report artifact upload
Jenkins	Documentation and pipeline sketch
Appendices	JUnit 5 comparison and BDD/API testing comparison

API Targets

The primary API target is Restful Booker, a public API commonly used for API automation practice. The framework uses it for CRUD, token authentication, cookie-authenticated protected operations, integration flows, schema validation, reporting examples, and capstone tests.

Early learning modules may also use:

• JSONPlaceholder for simple GET, query, and response-validation examples.
• Zippopotam.us for simple path-parameter and response-shape practice.

WireMock is used for deterministic negative/error scenarios so the framework does not depend on a public API failing on demand.

Project Structure

.
├── .github/workflows/              # GitHub Actions CI workflow
├── docs/                           # module-by-module learning documentation
├── src/main/java/com/learning/api/
│   ├── examples/                   # beginner Java/API learning examples
│   └── framework/                  # reusable API automation framework code
│       ├── client/                 # low-level Rest Assured API client
│       ├── config/                 # environment and framework config
│       ├── data/                   # JSON, CSV, Excel readers
│       ├── diagnostics/            # safe logging and masking
│       ├── endpoints/              # endpoint constants
│       ├── http/                   # request specification factory
│       ├── json/                   # Jackson mapper wrapper
│       ├── model/                  # request/response domain POJOs
│       ├── payload/                # payload builders
│       ├── schema/                 # schema classpath constants
│       └── service/                # booking-focused service layer
├── src/test/java/com/learning/api/tests/
│   ├── base/                       # BaseApiTest framework setup
│   ├── dataproviders/              # TestNG data providers
│   ├── framework/                  # local framework utility tests
│   ├── learning/                   # raw learning tests by module
│   ├── listeners/                  # Extent TestNG listener
│   ├── restfulbooker/              # live Restful Booker framework tests
│   └── wiremock/                   # local controlled negative tests
├── src/test/resources/
│   ├── config/                     # local environment config
│   ├── schemas/                    # JSON schema contract files
│   └── testdata/                   # JSON, CSV, Excel data
├── testng.xml                      # full framework suite
├── testng-parallel.xml             # conservative parallel smoke suite
└── pom.xml                         # Maven dependencies and plugins

Architecture

The final framework separates test intent from HTTP mechanics.

flowchart TD
    A["TestNG framework test"] --> B["BaseApiTest"]
    B --> C["BookingService"]
    C --> D["RestfulBookerClient"]
    D --> E["RequestSpecFactory"]
    E --> F["Rest Assured"]
    F --> G["Restful Booker API"]
    G --> H["Response"]
    H --> I["Assertions / schema validation / mapping"]
    J["BookingPayloadBuilder"] --> C
    K["JacksonJsonMapper"] --> C
    L["Data readers / DataProviders"] --> A
    M["SafeDiagnosticsFilter"] --> E
    N["Extent / Allure / Surefire"] --> A

Loading

Important framework files:

File	Purpose
BaseApiTest.java	Creates shared framework configuration, request specs, clients, and services for framework tests.
FrameworkConfig.java	Immutable configuration object for base URI, content type, and user agent.
ConfigReader.java	Loads environment-specific configuration from classpath properties.
RequestSpecFactory.java	Builds reusable Rest Assured request defaults and attaches safe diagnostics.
RestfulBookerEndpoints.java	Centralizes Restful Booker endpoint paths.
RestfulBookerClient.java	Owns low-level HTTP operations.
BookingService.java	Provides booking-focused operations used by tests.
BookingPayloadBuilder.java	Creates readable booking payloads with valid defaults and scenario-specific overrides.
JacksonJsonMapper.java	Centralizes Jackson serialization and deserialization.
RestfulBookerSchemas.java	Holds classpath paths for JSON schema files.
SafeDiagnosticsFilter.java	Logs masked request/response diagnostics only for HTTP failures.
SensitiveDataMasker.java	Masks password, token, authorization, and token-cookie values.
ExtentReportListener.java	Writes the Extent HTML report from TestNG lifecycle events.
WireMockBookingErrorTest.java	Demonstrates deterministic local 404/500 tests with WireMock.

Test Suites And Maven Commands

This project uses Maven Surefire to run TestNG tests. The default Maven command and the suite XML commands serve different learning purposes.

Default Discovery

mvn test

Runs discovered TestNG tests using Maven/Surefire. In the completed framework, this is a broad validation path and currently runs the full discovered suite.

Full Framework Suite

mvn test -DsuiteXmlFile=testng.xml

Runs the curated full suite from testng.xml. This is the best everyday confidence command and is also the command used by GitHub Actions.

The suite includes:

• setup and framework utility tests.
• Rest Assured learning tests.
• Restful Booker framework tests.
• data-driven tests.
• schema validation tests.
• WireMock negative tests.
• Extent listener reporting.
• Allure raw-result generation.

Parallel Smoke Suite

mvn test -DsuiteXmlFile=testng-parallel.xml

Runs the conservative parallel-safe slice from testng-parallel.xml with:

parallel="classes"
thread-count="3"

This suite intentionally includes local or stubbed classes first:

• config tests.
• Jackson mapping tests.
• data reader tests.
• sensitive-data masking tests.
• WireMock error tests.

It is a parallel smoke signal, not a replacement for the full suite.

Which Command Should I Use?

Goal	Command
Broad local validation	mvn test
Main framework confidence	mvn test -DsuiteXmlFile=testng.xml
Validate parallel-safe slice	mvn test -DsuiteXmlFile=testng-parallel.xml
Match CI behavior locally	mvn test -DsuiteXmlFile=testng.xml

Reports And Artifacts

After a suite run, inspect:

Artifact	Purpose
target/surefire-reports/	TestNG/Maven result files, stack traces, and stdout/stderr.
target/allure-results/	Raw Allure result/container files for later rendering.
target/extent-report/index.html	Directly viewable Extent HTML report.

Generated artifacts live under target/ and should not be committed.

Configuration

The default local environment config is:

src/test/resources/config/local.properties

Framework configuration is loaded through:

• Environment.java
• ConfigReader.java
• FrameworkConfig.java

The config layer keeps tests from hard-coding environment settings directly. The learning project defaults to Restful Booker, but the same pattern can grow into dev, qa, staging, or other environment profiles.

CI

GitHub Actions is configured in .github/workflows/api-tests.yml.

The workflow:

1. checks out the repository.
2. sets up Java 21 with Temurin.
3. caches Maven dependencies.
4. runs mvn test -DsuiteXmlFile=testng.xml.
5. uploads Surefire, Allure, and Extent artifacts with if: always().

The if: always() artifact upload matters because failed runs are when diagnostic evidence is most useful.

Jenkins is documented in docs/module-19-parallel-stability-cicd-jenkins/04-jenkins.md as an enterprise CI translation pattern. The executable CI artifact in this repository is GitHub Actions.

Learning Documentation

The module index is available in docs/README.md.

The implementation blueprint is plan.md.

Every module usually includes:

• 00-module-overview.md
• focused concept guides.
• exercises with hints and expected outcomes.
• interview review notes where useful.

The docs are intentionally learner-friendly and link back to concrete source files. This is a learning repo first and a framework repo second.

Portfolio Demonstration Flow

For a five-minute walkthrough, show:

1. README.md for the project story.
2. docs/README.md for the module learning path.
3. pom.xml for dependencies and Surefire configuration.
4. testng.xml and testng-parallel.xml for execution strategy.
5. BookingService.java and RestfulBookerClient.java for service/client boundaries.
6. BookingDataDrivenTest.java or BookingSchemaValidationTest.java for framework-style tests.
7. WireMockBookingErrorTest.java for controlled negative testing.
8. api-tests.yml for CI and artifact preservation.

Good portfolio talking points:

• "The repo is checkpointed module by module, so a learner can study the framework at any stage."
• "I started with direct Rest Assured syntax and moved repeated setup into reusable request specifications, clients, and services."
• "I use Jackson domain models and payload builders so tests read like API scenarios instead of raw JSON construction."
• "I validate both behavior and response contracts with assertions and JSON schema checks."
• "I use WireMock for controlled negative paths instead of depending on a public service to fail on demand."
• "Failure diagnostics are masked before logging, and reports are uploaded even when CI fails."

Documentation-Only Appendices

The executable framework stays focused on TestNG and Rest Assured.

JUnit 5 and Cucumber/BDD are covered as comparison appendices in Module 20:

• 04-junit5-comparison-appendix.md
• 05-bdd-api-testing-appendix.md

They are intentionally not executable dependencies in this project. Adding them would change the runner model and distract from the TestNG/Rest Assured learning path.

Reference Repositories

Reference repositories were used for ideas and curriculum comparison only. They were not copied wholesale into this project.

• Rest Assured concepts reference: https://github.com/PramodDutta/ATB10xAPIAutomationPrograms
• Rest Assured framework reference: https://github.com/PramodDutta/APIAutomationFramworkATB10x
• Selenium Java SDET learning framework style reference: https://github.com/lemegetonV/selenium-java-sdet-learning-framework