REST Assured Tutorial: API Testing in Java With Examples

What Is REST Assured?

REST Assured is a Java library that describes itself as a Java DSL for easy testing of REST services. It wraps an HTTP client and an assertion layer in a single fluent chain, so a request and its verification live in one expression instead of being split across a client call, a parse step, and a set of assertions.

It supports POST, GET, PUT, DELETE, OPTIONS, PATCH, and HEAD, and it can specify and validate parameters, headers, cookies, and request or response bodies. Because tests are ordinary Java classes, they sit in source control beside the application, go through code review, and run in the same build as everything else.

• Java teams already running Selenium or TestNG can add API coverage without introducing a second language or toolchain.
• Assertions read as behaviour, which makes a failure message useful to someone who did not write the test.
• Nothing about it is a browser tool, so API tests run in seconds and belong in the fast stage of a pipeline.

If you are still deciding what to cover at the service layer before writing code, our guide to REST API testing works through the request types and status handling this tutorial assumes you already know.

How Do You Set Up REST Assured in a Maven Project?

Add the dependency at test scope. The Maven coordinates are io.rest-assured:rest-assured, and version 6.0.1 requires a JDK of 17 or newer.

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

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>json-schema-validator</artifactId>
    <version>6.0.1</version>
    <scope>test</scope>
</dependency>

Two static imports keep the test bodies short. Import the entry points and the Hamcrest matchers, then set a base URI once so every test writes only the path.

import io.restassured.RestAssured;
import org.junit.jupiter.api.BeforeAll;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;

class PostApiTest {

    @BeforeAll
    static void setUp() {
        RestAssured.baseURI = "https://jsonplaceholder.typicode.com";
    }
}

Check your JDK before anything else. On Java 11 the dependency resolves and then fails at class load, which reads like a corrupt artifact rather than a version floor.

How Does the given/when/then Syntax Work?

The chain has three stages, and keeping them separate is what makes REST Assured tests readable. The canonical form in the project README is short enough to memorise.

given().
    param("key1", "value1").
    param("key2", "value2").
when().
    post("/somewhere").
then().
    body(containsString("OK"));

• given() builds the request: headers, query and path parameters, content type, authentication, and the body.
• when() fires exactly one HTTP method against a path, and it is the only stage that touches the network.
• then() asserts on what came back, chaining as many status, header, and body checks as the case needs.

A test that skips given() entirely is valid when there is nothing to configure. Starting a chain at when() for a plain GET is idiomatic, not a shortcut.

How Do You Write CRUD Tests in REST Assured?

The four tests below form a complete CRUD suite against a public API, so they run without a local server. Before writing the assertions we called each endpoint directly and recorded what it actually returns.

GET    /posts/1  -> 200  application/json
   { "userId": 1, "id": 1, "title": "sunt aut facere repellat provident ...", "body": "quia et suscipit ..." }
POST   /posts    -> 201  application/json
   { "title": "rest assured", "body": "crud demo", "userId": 1, "id": 101 }
PUT    /posts/1  -> 200  application/json
   { "id": 1, "title": "updated", "body": "updated body", "userId": 1 }
DELETE /posts/1  -> 200  application/json
   {}

Two details from that run change how the tests are written. The create returns 201 rather than 200, and the delete returns 200 with an empty object rather than 204. Assert what the API does, not what the HTTP conventions suggest it should do.

@Test
void getPostReturnsExpectedFields() {
    given()
        .pathParam("id", 1)
    .when()
        .get("/posts/{id}")
    .then()
        .statusCode(200)
        .contentType(ContentType.JSON)
        .body("id", equalTo(1))
        .body("userId", equalTo(1))
        .body("title", not(emptyString()));
}

@Test
void createPostReturns201() {
    String payload = """
        {
          "title": "rest assured",
          "body": "crud demo",
          "userId": 1
        }
        """;

    given()
        .contentType(ContentType.JSON)
        .body(payload)
    .when()
        .post("/posts")
    .then()
        .statusCode(201)
        .body("title", equalTo("rest assured"))
        .body("id", notNullValue());
}

@Test
void updatePostReplacesFields() {
    Map<String, Object> payload = Map.of(
        "id", 1,
        "title", "updated",
        "body", "updated body",
        "userId", 1
    );

    given()
        .contentType(ContentType.JSON)
        .body(payload)
    .when()
        .put("/posts/1")
    .then()
        .statusCode(200)
        .body("title", equalTo("updated"))
        .body("body", equalTo("updated body"));
}

@Test
void deletePostSucceeds() {
    when()
        .delete("/posts/1")
    .then()
        .statusCode(200);
}

How Do You Validate JSON Responses and Schemas?

Field assertions catch wrong values. They do not catch a field that quietly disappeared or changed type, which is the failure mode that breaks consumers. Schema validation covers that gap.

import static io.restassured.module.jsv.JsonSchemaValidator.matchesJsonSchemaInClasspath;

@Test
void postMatchesContract() {
    when()
        .get("/posts/1")
    .then()
        .statusCode(200)
        .body(matchesJsonSchemaInClasspath("post-schema.json"));
}

The schema lives in src/test/resources and describes the contract rather than the data. Requiring the fields and pinning their types is usually enough to catch drift.

{
  "type": "object",
  "required": ["id", "userId", "title", "body"],
  "properties": {
    "id":     { "type": "integer" },
    "userId": { "type": "integer" },
    "title":  { "type": "string" },
    "body":   { "type": "string" }
  }
}

For collections, JsonPath expressions handle aggregate checks in one line. Asserting body("size()", greaterThan(0)) on a list endpoint, or extracting with path("[0].id"), avoids looping in the test.

How Do You Handle Authentication in REST Assured?

REST Assured has first class support for the common schemes, so authentication is part of the given() stage rather than manual header assembly.

// Basic, sent immediately instead of waiting for a 401 challenge
given().auth().preemptive().basic(username, password)

// Bearer token
given().auth().oauth2(accessToken)

// Any custom scheme
given().header("Authorization", "ApiKey " + apiKey)

Prefer preemptive basic auth in tests. Without it REST Assured waits for a challenge, which doubles the request count and fails outright against servers that return 403 instead of 401.

Read credentials from environment variables, never from a committed file. A token in a test resource is a token in your git history, and rotating it later does not remove it.

Note: API tests prove the contract holds. They cannot tell you the screen consuming that response still renders. TestMu AI pairs both layers in one pipeline. Try TestMu AI free!

Which REST Assured 6 Changes Break Existing Suites?

Version 6 is the first release line in years that breaks builds on purpose, and most tutorials still describe 5.x behaviour. These are the changes the changelog records for 6.0.0 and 6.0.1.

That last entry is a genuine denial-of-service fix, credited in the changelog to a security researcher who reported it privately. If your tests parse JSON you do not control, such as a third party sandbox or a fuzzing target, the cap is configurable.

// Default is 1000 characters; a negative value disables the check entirely
RestAssured.config = RestAssured.config()
    .jsonConfig(JsonConfig.jsonConfig().numberLengthLimit(1000));

How Do You Run REST Assured Tests in CI?

REST Assured tests are ordinary JUnit or TestNG tests, so Maven runs them with no extra plugin. Pin the JDK to 17 or newer and the job is three lines.

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '17'

- name: API contract tests
  run: mvn -B test

A green API suite proves the contract holds. It says nothing about the screen consuming that response, which is where the next class of failure lives: a button wired to the wrong endpoint, a redirect that 404s, a form that never validates. The code is correct and the user-facing result is broken.

That second layer is what Kane CLI covers. It is a deterministic browser agent that drives real Chrome from a natural language objective and verifies the rendered result, so it gates the same pipeline immediately after the API stage.

npm install -g @testmuai/kane-cli

# Agent mode emits machine-readable output and needs no display server
kane-cli run "Open the orders page and confirm the latest order appears" --agent --headless

Both stages gate on exit codes, so the pipeline logic stays uniform. Kane CLI returns 0 for a pass, 1 for a failed assertion, 2 for an error such as an auth failure, and 3 for a timeout or cancellation. The Kane CLI getting started documentation covers authentication and configuration.

What Are REST Assured Best Practices?

• Centralise configuration in a RequestSpecification built once with RequestSpecBuilder, so switching environments is a one line change rather than an edit across every class.
• Assert on shape and invariants rather than on seed data. Pinning an exact title couples the test to a fixture that someone will eventually change.
• Use log().ifValidationFails() instead of log().all(), which keeps CI output readable while still printing the payload when something breaks.
• Keep one HTTP call per test. A chain that creates, updates, and deletes in a single method reports one failure for four possible causes.
• Validate against a schema for any endpoint another team consumes, because field assertions cannot see a removed field they never checked.
• Run mvn dependency:tree after any upgrade. Most REST Assured failures that look like library bugs are Groovy or Jackson version clashes.

Where REST Assured fits against other options is a separate decision, and our comparison of API testing tools covers the trade-offs. For broader service layer strategy, including parallel execution and backward compatibility, see our session write up on REST API automation strategies.

Conclusion

Start by checking your JDK, then add the 6.0.1 dependency and port one existing test to the given/when/then chain. The four CRUD examples above run against a public API, so you can confirm your setup works before pointing anything at your own service.

Once the suite is green in CI, the remaining risk moves up a layer to the interface consuming those endpoints. TestMu AI runs that verification in the same pipeline through Kane CLI, and the getting started documentation linked above walks through installation and authentication. If you are preparing for a role rather than a release, our REST API interview questions cover the same ground from the other side of the table.