Cucumber and REST Assured: a worked API testing example

How to combine Cucumber's readable scenarios with REST Assured's HTTP checks, from a first step definition to a reusable set of generic API steps.

By Joseph Ofoma · 5 October 2026 · 8 min read

REST Assured is the standard Java library for testing HTTP APIs, and Cucumber turns tests into plain-English scenarios that the whole team can read. Together they give you API tests that read like the test case and fail with useful detail. The examples below use Restful-booker, a free practice API.

Plain REST Assured first

Here's a test that creates a booking, without Cucumber:

given()
    .baseUri("https://restful-booker.herokuapp.com")
    .contentType(ContentType.JSON)
    .body(new File("src/test/resources/testdata/payloads/new-booking.json"))
.when()
    .post("/booking")
.then()
    .statusCode(200)
    .body("booking.firstname", equalTo("Jim"))
    .body("bookingid", notNullValue())
    .body(matchesJsonSchemaInClasspath("schemas/create-booking-response.json"));

It's concise, but only a developer will read it, and every new check means new Java.

The same test as a Cucumber scenario

@api @smoke
Scenario: Create a booking from a JSON file
  When I send a POST request to "/booking" with the body from "payloads/new-booking.json"
  Then the response status code should be 200
  And the response field "booking.firstname" should be "Jim"
  And the response field "bookingid" should not be empty
  And the response should match the JSON schema "create-booking-response.json"
  And the response time should be under 10000 milliseconds

Now a tester, developer or product owner can read it and compare it with the manual test case.

Writing the step definitions

The key design decision is to write steps that are generic, so the path, field and value are parameters, rather than one step per test. The steps also need somewhere to keep the request being built and the last response. Put that in a small session class that's created fresh for each scenario:

public class ApiSession {
    private final Map<String, String> headers = new HashMap<>();
    private final Map<String, Object> saved = new HashMap<>();
    private Response lastResponse;

    public Response send(Method method, String path, Object body) {
        // SerenityRest wraps REST Assured and records each call in the report
        RequestSpecification request = SerenityRest.given().baseUri(baseUrl()).headers(headers);
        if (body != null) request.contentType(ContentType.JSON).body(body);
        lastResponse = request.request(method, path);
        return lastResponse;
    }
    // remember(name, value), resolve("${name}"), lastResponse() ...
}

The step definitions then become thin wrappers:

@When("I send a {word} request to {string}")
public void send(String method, String path) {
    api.send(Method.valueOf(method), api.resolve(path), null);
}

@Then("the response status code should be {int}")
public void statusCode(int expected) {
    assertThat(api.lastResponse().statusCode()).isEqualTo(expected);
}

@Then("the response field {string} should be {string}")
public void fieldEquals(String path, String expected) {
    assertThat(api.lastResponse().jsonPath().getString(path)).isEqualTo(api.resolve(expected));
}

@When("I save the response field {string} as {string}")
public void save(String path, String name) {
    api.remember(name, api.lastResponse().jsonPath().get(path));
}

In Serenity BDD, declare the session as @Steps(shared = true) ApiSession api; in each step class. Every step class in a scenario then shares the same session, and each scenario gets a fresh one, so parallel tests never see each other's values.

Chaining requests with saved values

Real API tests usually need data from one response in the next request. With ${name} placeholders resolved by the session, that stays readable:

Scenario: Delete a booking as an authenticated user
  Given I am authenticated as the booking admin
  And a booking exists for "Dan" "Delete"
  When I send a DELETE request to "/booking/${bookingId}"
  Then the response status code should be 201
  When I send a GET request to "/booking/${bookingId}"
  Then the response status code should be 404

The first two steps are domain steps: business-level shortcuts for set-up that would otherwise take several lines. They use the same session, so the booking ID they save is available to the generic steps:

@Given("a booking exists for {string} {string}")
public void bookingExistsFor(String firstname, String lastname) {
    Response response = api.send(Method.POST, "/booking", Booking.forGuest(firstname, lastname));
    assertThat(response.statusCode()).as("create booking status").isEqualTo(200);
    api.remember("bookingId", response.jsonPath().getInt("bookingid"));
}

Validate the whole response with JSON schemas

Field checks confirm the values you care about. A JSON schema check confirms the whole response shape, catching renamed fields, wrong types and missing properties that no individual assertion looked for. REST Assured's json-schema-validator module does this with one call, and if your API has an OpenAPI spec, the schemas can be generated from its response definitions.

Keep secrets out of the scenarios

Usernames, passwords and tokens should never be in a feature file. Read them from configuration, which can be overridden by environment variables or CI secrets. For example, TestConfig.get("api.password") checks a -D system property, then an API_PASSWORD environment variable, then serenity.conf.

Tips

All of this, ready to run

EffortlessATF includes the session, the generic API steps, schema validation and working Restful-booker examples. Clone it, run one command, and read the report.