API Test Automation using Builder Pattern

API Test Automation with REST Assured Using the Builder Pattern

If you’re setting up API test automation with REST Assured, one of the biggest challenges you’ll eventually run into isn’t the framework itself — it’s payload management. As your test suite grows, hardcoded JSON strings and duplicated request objects turn into a maintenance nightmare. This is exactly where the Builder pattern earns its place in your automation toolkit. In this guide, you’ll learn how to achieve API Test Automation using Builder Pattern in REST Assured.

What Is REST Assured?

REST Assured is a Java-based library used for testing and validating REST APIs. It provides a fluent, readable syntax (similar to BDD-style given(), when(), then()) that makes writing API tests straightforward, even for testers who aren’t deeply familiar with HTTP internals.

REST Assured handles:

• Sending HTTP requests (GET, POST, PUT, DELETE, PATCH)
• Validating response status codes, headers, and body content
• Serialization and deserialization of JSON/XML payloads
• Authentication (Basic, OAuth, Bearer tokens)

Why Use the Builder Pattern for Payload Creation?

Most API tests require sending a request body — often a complex JSON object with nested fields, optional parameters, and varying combinations depending on the test scenario. Without a structured approach, teams typically end up with:

• Duplicated JSON strings scattered across test classes
• POJOs with dozens of constructor overloads
• Fragile tests that break when a field is added or renamed

The Builder pattern solves this by letting you construct payload objects step by step, using a fluent, chainable API. Instead of a constructor with ten parameters (most of which you don’t care about for a given test), you only set the fields relevant to that test case.

Benefits of using the Builder pattern in API automation:

1. Readability – Tests clearly show which fields are being set and why.
2. Reusability – A base builder can be extended or reused across multiple test classes.
3. Flexibility – Easily create valid, invalid, or partial payloads for negative testing.
4. Maintainability – Adding a new field to the payload doesn’t break existing tests.

Project Setup

Before writing tests, add the required dependencies to your pom.xml (Maven):

<dependencies>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <version>5.4.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testng</groupId>
        <artifactId>testng</artifactId>
        <version>7.10.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

You can use JUnit instead of TestNG if that fits your project better — the Builder pattern concept stays identical.

Step 1: Create the Payload POJO

Let’s automate a simple User creation API. First, define the POJO that represents the request payload.

public class User {
    private final String name;
    private final String email;
    private final int age;
    private final String role;
    private User(UserBuilder builder) {
        this.name = builder.name;
        this.email = builder.email;
        this.age = builder.age;
        this.role = builder.role;
    }
    public String getName() { return name; }
    public String getEmail() { return email; }
    public int getAge() { return age; }
    public String getRole() { return role; }
    public static class UserBuilder {
        private String name;
        private String email;
        private int age;
        private String role;
        public UserBuilder withName(String name) {
            this.name = name;
            return this;
        }
        public UserBuilder withEmail(String email) {
            this.email = email;
            return this;
        }
        public UserBuilder withAge(int age) {
            this.age = age;
            return this;
        }
        public UserBuilder withRole(String role) {
            this.role = role;
            return this;
        }
        public User build() {
            return new User(this);
        }
    }
}

Notice the private constructor and static nested UserBuilder class — this is the classic Builder pattern structure. The User object itself stays immutable, which prevents accidental modification once it’s built.

Step 2: Build Payloads Fluently in Your Tests

With the builder in place, creating payloads inside your test methods becomes clean and expressive:

User validUser = new User.UserBuilder()
        .withName("John Doe")
        .withEmail("john.doe@example.com")
        .withAge(29)
        .withRole("admin")
        .build();

Need a payload with a missing field for negative testing? Just skip it:

User userMissingEmail = new User.UserBuilder()
        .withName("Jane Doe")
        .withAge(24)
        .withRole("user")
        .build();

No overloaded constructors, no null placeholders — just the fields relevant to that scenario.

Step 3: Integrate the Builder with REST Assured

Now let’s wire this into an actual REST Assured test:

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
public class UserApiTest {
    @Test
    public void shouldCreateUserSuccessfully() {
        RestAssured.baseURI = "https://api.example.com";
        User validUser = new User.UserBuilder()
                .withName("John Doe")
                .withEmail("john.doe@example.com")
                .withAge(29)
                .withRole("admin")
                .build();
        given()
                .contentType(ContentType.JSON)
                .body(validUser)
            .when()
                .post("/users")
            .then()
                .statusCode(201)
                .body("name", equalTo("John Doe"))
                .body("role", equalTo("admin"));
    }
    @Test
    public void shouldFailWhenEmailIsMissing() {
        User invalidUser = new User.UserBuilder()
                .withName("Jane Doe")
                .withAge(24)
                .withRole("user")
                .build();
        given()
                .contentType(ContentType.JSON)
                .body(invalidUser)
            .when()
                .post("/users")
            .then()
                .statusCode(400);
    }
}

REST Assured automatically serializes the User object into JSON using an underlying serializer (Jackson or Gson, depending on what’s on your classpath), so you don’t need to manually convert the builder output into a JSON string.

Step 4: Extend the Builder for Complex Payloads

Real-world APIs often need nested objects — for example, a User with an Address. The Builder pattern scales well here too:

public class Address {
    private final String street;
    private final String city;
    private final String zipCode;
    private Address(AddressBuilder builder) {
        this.street = builder.street;
        this.city = builder.city;
        this.zipCode = builder.zipCode;
    }
    public static class AddressBuilder {
        private String street;
        private String city;
        private String zipCode;
        public AddressBuilder withStreet(String street) {
            this.street = street;
            return this;
        }
        public AddressBuilder withCity(String city) {
            this.city = city;
            return this;
        }
        public AddressBuilder withZipCode(String zipCode) {
            this.zipCode = zipCode;
            return this;
        }
        public Address build() {
            return new Address(this);
        }
    }
}

Then add an Address field to the User builder using the same withX() convention, and nest the builders when constructing test data:

Address address = new Address.AddressBuilder()
        .withStreet("221B Baker Street")
        .withCity("London")
        .withZipCode("NW16XE")
        .build();
User userWithAddress = new User.UserBuilder()
        .withName("Sherlock Holmes")
        .withEmail("sherlock@example.com")
        .withAge(40)
        .withRole("detective")
        .withAddress(address)
        .build();

Best Practices for Builder-Based Payloads in API Automation

• Keep builders in a dedicated package (e.g., test.builders) separate from your test classes and API clients.
• Provide sensible defaults in the builder for fields that rarely change, so tests only override what’s relevant.
• Combine with the Object Mother or Test Data Factory pattern if you need pre-configured payload variants (e.g., UserTestData.validAdmin()).
• Avoid logic in builders — builders should only assemble data, not validate or transform it.
• Pair builders with a Page Object–style API client class to keep endpoint calls out of your test methods entirely.

Conclusion

Setting up API test automation with REST Assured becomes significantly easier to maintain once you introduce the Builder pattern for payload creation. It removes duplication, improves readability, and makes it simple to generate both valid and invalid test data without bloated constructors or brittle JSON strings.

Start small — apply the Builder pattern to your most frequently used payload, then expand it across your test suite as your API automation framework matures.

Related Links

• What is API Testing
• REST HTTP Methods
• What is REST Assured
• Setup
• First Test
• Request Specification Explained
• E2E API Testing Flow
• Response Validation
• Authentication methods
• API framework design
• CI/CD Integration for REST Assured