REST Assured

The Hook: API Testing for Grown-ups

Postman is great for a quick check, but it's a "UI tool." If you're building a massive banking app, you don't want to click buttons to test 500 different API endpoints. You want a Code Tool. REST Assured is the industry standard for Java teams to automate API testing with speed and precision.

It reads like English, runs like lightning, and integrates perfectly with your existing Java build pipeline. No more "I forgot to save the collection" — your tests live in Git, right next to the code.

The Rule: The Contract First Principle

An API is a contract between the Frontend and the Backend. The Rule: Verify the Status, then the Data. If the status isn't 200 OK, don't even bother looking at the data. REST Assured makes this order mandatory in its syntax, keeping your tests logical and easy to debug.

The Analogy: The Postal Service

Think of an API call like sending a registered letter. The Headers are the address on the envelope. The Auth Token is your ID shown to the postie. The Body is the letter inside. REST Assured is the quality inspector at the post office checking that the envelope is addressed correctly, the ID is valid, and the letter isn't empty.

The Setup: Adding the DSL

To use REST Assured, add this to your pom.xml. We call it a "DSL" because it changes the way Java looks to make it feel like a testing language.

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>rest-assured</artifactId>
    <version>5.3.0</version>
    <scope>test</scope>
</dependency>

The First Script: Given / When / Then

This is the magic of REST Assured. It uses the Given/When/Then pattern to structure your test:

import static io.restassured.RestAssured.*;
import static org.hamcrest.Matchers.*;

test("Check user details") {
    given()
        .baseUri("https://api.example.com")
        .header("Content-Type", "application/json")
    .when()
        .get("/users/1")
    .then()
        .statusCode(200)
        .body("name", equalTo("Leanne Graham"))
        .body("email", containsString("@"));
}

The "Gotcha": The GPath Trap

When you want to find a value deep inside a JSON response, REST Assured uses something called GPath. It's powerful but picky. If your JSON is { "users": [{ "id": 1 }] }, you can't just ask for id.

The Framework: Hamcrest Matchers

REST Assured doesn't just check for equality; it uses Hamcrest Matchers for sophisticated validation:

• greaterThan(0): Useful for checking ID fields.
• hasSize(5): Checks the length of a list.
• notNullValue(): Ensures a field isn't empty.
• anyOf(equalTo(200), equalTo(201)): Handles multiple success codes.

The NZ Example: Address Validator

In NZ, we often use the PostNZ Address API. Let's test a mock version of it.

test("Validate Wellington Postcode") {
    given()
        .queryParam("street", "101 Customhouse Quay")
        .queryParam("city", "Wellington")
    .when()
        .get("/address/validate")
    .then()
        .statusCode(200)
        .body("postcode", equalTo("6011"))
        .body("region", equalTo("Wellington"));
}

The Pro Move: JSON Schema Validation

Checking every field manually is slow. Seniors use JSON Schema. A schema is a "Blueprint" of what the response should look like. With one line of code, you can validate that 100 fields all have the correct type and structure.

.then()
    .assertThat()
    .body(matchesJsonSchemaInClasspath("user-schema.json"));

The Challenge: Your Turn

We have a mock API at /api/v1/health that returns {"status": "up", "uptime": 12345}.