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
- Write generic steps once; write domain steps only for set-up and complex flows.
- One session per scenario, shared across step classes, created fresh each time.
- Load request bodies from JSON files or typed objects, not long inline strings.
- Check the status, the key fields and the schema.
- Let the report show every request and response; Serenity does this automatically for calls made through
SerenityRest.
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.