Request and Response Handling in Cucumber with REST Assured

What Is Request and Response Handling?

Request and response handling is the core activity of API automation. In a Cucumber and REST Assured framework, it means building HTTP requests, sending them to an API, receiving HTTP responses, extracting response data, validating returned information, and reusing useful values in later steps or scenarios when the design requires it. Every API test, whether simple or enterprise-level, depends on this flow.

Request handling focuses on the data sent to the API. It includes the base URI, endpoint, HTTP method, headers, authentication, query parameters, path parameters, cookies, form parameters, and request body. Response handling focuses on the data returned by the API. It includes the status code, headers, cookies, response body, response time, content type, error messages, generated IDs, and business fields.

In simple terms, request handling sends data to an API, while response handling processes and validates the data returned by the API. REST Assured provides the Java methods to perform this work. Cucumber provides the readable scenario structure that explains why the request is being sent and what behavior should be validated.

Why Request and Response Handling Is Important

Every REST API interaction follows a predictable pattern. A client builds an HTTP request, sends it to a REST API, waits for the API to process it, receives an HTTP response, and validates whether the response matches the expected contract. If any part of this flow is weak, the automation becomes unreliable. A malformed request may fail for the wrong reason. A weak response assertion may allow defects to pass. Poor extraction logic may break later API calls.

Without proper request and response handling, requests may be malformed, responses cannot be validated properly, test data cannot be reused safely, and API workflows become unreliable. This is especially risky in chained API tests where one API creates data, another retrieves it, another updates it, and another deletes it. If the framework does not manage request and response data carefully, failures become hard to diagnose.

Good handling also improves maintainability. Instead of repeating the same headers, base URI, token setup, and validation logic in every step definition, a framework can centralize these details. Step definitions remain thin. Feature files remain readable. API client classes handle request execution. Validator classes handle response assertions. Scenario context stores temporary values. This separation keeps the suite scalable.

Request and Response Lifecycle

The request and response lifecycle begins before the HTTP call is sent. The framework must decide which environment to use, what base URL applies, what authentication is required, which endpoint is being called, which method is needed, and what data should be sent. A strong framework makes this setup consistent through configuration files, request specifications, authentication utilities, request builders, and API service classes.

Build request
Add headers
Add authentication
Add parameters
Add request body
Send request
Receive response
Validate response
Extract data
Reuse data when needed

After the response is received, the framework should validate it at the correct level. Some scenarios need only a status code and a business field. Other scenarios need headers, schema validation, nested JSON checks, response time, or error contract verification. The level of validation should match the purpose of the scenario. Checking everything in every scenario creates noise. Checking only status codes creates weak tests.

HTTP Request Components

A typical HTTP request contains several parts. The base URI identifies the host, such as an API server. The endpoint identifies the resource or action, such as /users or /orders/{id}. The HTTP method describes the operation, such as GET, POST, PUT, PATCH, DELETE, OPTIONS, or HEAD. Headers carry metadata such as content type, accepted response format, authorization token, correlation ID, or user agent.

Parameters add more detail to the request. Query parameters appear in the URL after a question mark and are commonly used for filtering, pagination, sorting, and searching. Path parameters are part of the URL path and usually identify a resource. Cookies are used in some session-based APIs. Authentication proves the client has permission to call the API. The request body carries structured data for methods such as POST, PUT, and PATCH.

HTTP Request
  Base URI
  Endpoint
  HTTP Method
  Headers
  Query Parameters
  Path Parameters
  Cookies
  Authentication
  Request Body

Understanding these parts is essential because many API failures are caused by incorrect request construction. A missing header, expired token, wrong path parameter, malformed JSON body, or incorrect content type can all cause failures. Good request handling makes these parts visible in the framework while keeping feature files clean.

HTTP Response Components

An HTTP response is the API's answer to the request. It contains a status code, response headers, response body, cookies, response time, and content type. The status code gives a quick signal about success or failure. The response body contains the actual data or error details. Headers provide metadata. Cookies may maintain session state. Response time helps measure whether the API responds within an acceptable limit.

HTTP Response
  Status Code
  Headers
  Response Body
  Cookies
  Response Time
  Content Type

Response handling is more than checking that a request did not fail. A 200 response may still contain incorrect data. A 400 response may still have the wrong error message. A 201 response may create a resource but miss a required field. Strong automation validates the parts of the response that matter for the scenario and API contract.

Request Handling in REST Assured

REST Assured uses a fluent syntax that separates request preparation from request execution. The given() section is used to build the request. The when() section sends the request. The returned Response object contains the API response. This style is readable and works naturally with reusable Java methods.

Response response =
    given()
        .contentType(ContentType.JSON)
        .body(requestBody)
    .when()
        .post("/users");

The code reads like a flow. Given a JSON request body, when a POST request is sent to the users endpoint, REST Assured returns a response. In real frameworks, this code is usually placed inside an API client or service class rather than directly inside the step definition. That keeps the Cucumber layer focused on scenario mapping instead of request mechanics.

Request Specification

A RequestSpecification is one of the most useful REST Assured features for framework design. It allows common request configuration to be built once and reused across many API calls. Instead of repeating base URI, content type, accept header, authentication, and logging configuration everywhere, the framework can centralize them in a common method or factory class.

RequestSpecification request =
    given()
        .baseUri(BASE_URL)
        .contentType(ContentType.JSON)
        .header("Accept", "application/json");

Later, the same request specification can be reused with different bodies or endpoints.

Response response =
    request
        .body(payload)
        .post("/users");

This improves consistency and reduces duplication. It also makes environment changes easier. If the base URL or default headers change, the update can be made in one place. In enterprise frameworks, request specifications are often created by a RequestSpecFactory or BaseApiClient class.

Base URI and Environment Configuration

The base URI should not be hardcoded across step definitions or API clients. A framework may need to run against local, QA, staging, UAT, pre-production, or production-like environments. If base URLs are scattered throughout the code, switching environments becomes risky. Configuration files or environment variables should provide the base URL.

RestAssured.baseURI = "https://api.example.com";

This direct assignment is fine for a small example, but real frameworks usually read the value from configuration.

baseUrl=https://api.example.com

Externalized configuration improves portability. CI/CD pipelines can pass environment-specific values without changing code. It also reduces the chance of accidentally running tests against the wrong environment. The feature file should not mention the base URI unless environment behavior itself is being tested.

HTTP Methods

REST Assured supports the common HTTP methods used in REST APIs. GET retrieves data. POST creates or submits data. PUT replaces a resource. PATCH partially updates a resource. DELETE removes a resource. OPTIONS asks what operations are supported. HEAD retrieves headers without the response body. Knowing the purpose of each method helps design meaningful API scenarios.

Response response =
    given()
    .when()
    .get("/users");

The feature file should usually describe the behavior rather than the method. For example, "When the client requests user details" is often better than "When GET request is sent." The API client can decide that the operation uses GET. However, status-code or method-specific behavior can still be validated when it is part of the API contract.

Request Headers

Headers carry metadata about the request. Common headers include Authorization, Accept, Content-Type, User-Agent, correlation ID, trace ID, and custom application headers. Headers tell the API what kind of data is being sent, what response format the client accepts, who the client is, and how the request should be processed.

given()
    .header("Authorization", "Bearer " + token)
    .header("Accept", "application/json")
    .header("Content-Type", "application/json");

Headers should be managed consistently. Authorization headers should be added by authentication utilities or request specifications. Content-Type and Accept headers can often be part of the default request setup. Scenario-specific headers can be added by the API client when needed. Avoid repeating the same header setup in every step definition.

Header mistakes are common. A missing Content-Type may cause the API to reject the body. A wrong Accept header may return an unexpected response format. An expired Authorization token may return 401. Good logging and reusable request specifications make these issues easier to detect.

Query Parameters

Query parameters appear after the question mark in a URL. They are commonly used for filtering, pagination, sorting, searching, and optional request controls. For example, /users?page=2 requests the second page of users. REST Assured supports query parameters through queryParam().

Response response =
    given()
        .queryParam("page", 2)
    .when()
        .get("/users");

Feature files should describe query parameter behavior in readable language. Instead of saying "When query parameter page is 2," the scenario can say, "When the client requests the second page of users." The API client can convert that intent into a query parameter. This style keeps Gherkin readable while still testing the actual request behavior.

Path Parameters

Path parameters are variables inside the endpoint path. They are commonly used to identify a resource. For example, /users/25 may retrieve the user whose ID is 25. REST Assured provides pathParam(), which is cleaner and safer than string concatenation.

Response response =
    given()
        .pathParam("id", 25)
    .when()
        .get("/users/{id}");

This approach improves readability and reduces mistakes. In Cucumber, the user ID may come from test data, a previous response, or scenario context. The step definition can retrieve the ID and pass it to the API client. The API client can use it as a path parameter.

Form Parameters and Cookies

Form parameters are used when an API expects form-encoded data instead of a JSON body. This is common in some login flows, legacy systems, or OAuth-related endpoints. REST Assured supports form parameters through formParam().

given()
    .formParam("username", "admin")
    .formParam("password", "admin123");

Cookies are useful for session-based authentication or applications that still depend on server-side sessions. REST Assured allows cookies to be added to requests and extracted from responses.

given()
    .cookie("SESSIONID", sessionId);

Modern API automation often uses bearer tokens, but cookies and form parameters still appear in real projects. A good framework should support them when the application requires them while keeping their handling centralized and secure.

Authentication

Authentication proves that the API client is allowed to access a resource. REST Assured supports common authentication styles such as bearer token authentication, basic authentication, digest authentication, and custom header-based authentication. The most common modern pattern is a bearer token in the Authorization header.

given()
    .auth()
    .oauth2(token);

Basic authentication can also be configured through REST Assured.

given()
    .auth()
    .preemptive()
    .basic("admin", "password");

Authentication logic should not be duplicated in every scenario. A framework should generate or retrieve tokens through an AuthService, store them safely for the current scenario or test run, and inject them through request specifications. Tokens should not be hardcoded in feature files or committed to source control.

Request Body

The request body carries the data sent to the API. REST Assured can send a body as a raw JSON string, POJO, Map, file, or other serializable object. For a small example, a JSON string may be fine. For larger frameworks, POJOs and request builders often provide better structure and type safety.

given()
    .contentType(ContentType.JSON)
    .body(userRequest)
.when()
    .post("/users");

REST Assured can automatically serialize supported Java objects into JSON when the required serialization library is available. This makes POJO-based request bodies convenient. The feature file can describe the data at a business level, the step definition can build a request object, and the API client can send it.

Raw JSON is still useful for some scenarios, especially when testing malformed payloads, missing fields, or exact request shapes. The right body style depends on readability, maintainability, and the purpose of the test.

Sending the Request

After the request is prepared, REST Assured sends it with a method call such as get(), post(), put(), patch(), or delete(). The API processes the request and returns a response. In a clean framework, sending the request is usually done inside an API service method.

Response response =
    given()
        .body(request)
    .when()
        .post("/users");

The step definition should not contain long chains of REST Assured calls for every scenario. It should call a method such as userApi.createUser(request). That method can handle the request specification, endpoint, HTTP method, logging, and response return. This keeps the Cucumber layer thin.

The Response Object

REST Assured stores the returned API response in a Response object. This object gives access to status code, headers, body, cookies, content type, response time, and extraction methods. The response object is central to response handling because almost every validation or chained action depends on it.

Response response;

In a Cucumber framework, the response may be stored in scenario context so that later Then steps can validate it. For example, a When step sends a request and stores the response. A Then step validates status code. Another Then or And step validates the response body. This keeps the scenario flow natural.

However, response storage should be scoped carefully. Do not use global static response variables in a way that breaks parallel execution. Prefer scenario-scoped context objects or dependency injection when the framework supports it.

Status Code Validation

Status code validation is the first level of response validation. It confirms whether the API returned the expected high-level result. Common success codes include 200 OK, 201 Created, and 204 No Content. Common client error codes include 400 Bad Request, 401 Unauthorized, 403 Forbidden, and 404 Not Found. Server errors often appear as 500-level responses.

response.then()
    .statusCode(201);

Status code validation is important, but it is not enough. A response can return 200 and still contain wrong data. A 400 response can still have an incorrect error message. A 201 response can create a resource with missing or incorrect fields. Use status code checks as the starting point, not the full validation strategy.

Response Body Validation

Response body validation checks the actual returned data. REST Assured supports body assertions using JsonPath and matchers. A test can validate simple fields, nested fields, list sizes, values inside arrays, error objects, and business data. This is where many API defects are discovered.

response.then()
    .body("name", equalTo("John"));

Multiple validations can be chained when they belong to the same response contract.

response.then()
    .body("name", equalTo("John"))
    .body("job", equalTo("QA"));

In larger frameworks, response validation is often placed inside validator classes. For example, UserResponseValidator can contain methods such as verifyUserCreated() or verifyInvalidPasswordError(). This keeps step definitions readable and prevents repeated JSONPath assertions.

Header Validation

Headers are part of the API response contract. Content-Type, cache headers, security headers, rate-limit headers, correlation IDs, and pagination metadata may all be important. REST Assured can validate headers directly.

response.then()
    .header("Content-Type", containsString("application/json"));

Header validation should match the scenario purpose. A general API test may validate Content-Type. A tracing scenario may validate a correlation ID. A performance or gateway scenario may validate caching or rate-limit headers. Avoid validating every header in every test unless the project has a clear reason. Too many low-value assertions increase maintenance noise.

Response Time Validation

Response time validation checks whether the API responds within an acceptable time. REST Assured supports time assertions. This can be useful for basic performance expectations, smoke tests, and service-level checks.

response.then()
    .time(lessThan(3000L));

Response time assertions should be used carefully. API timing can vary because of environment load, network conditions, CI machines, database state, and external dependencies. A strict time check may cause flaky tests if the environment is unstable. For serious performance testing, use dedicated performance tools. In functional API automation, keep time checks realistic and limited to scenarios where response time is part of the acceptance expectation.

Extracting Response Values

Many API workflows require data from one response to be used in another request. For example, a create user call may return a user ID. The test may need that ID to retrieve, update, or delete the same user. REST Assured allows values to be extracted from the response using JsonPath.

String id =
    response.jsonPath()
        .getString("id");

Extraction should be clear and purposeful. Do not extract values just because they exist. Extract values that are needed for validation, chaining, cleanup, or reporting. Store them in a scenario-scoped context object so later steps can access them safely.

Extracting Nested Values

API responses often contain nested JSON structures. A user object may contain a profile, address, roles, permissions, and metadata. REST Assured JsonPath can extract nested values using dot notation.

{
  "user": {
    "name": "John"
  }
}

String name =
    response.jsonPath()
        .getString("user.name");

Nested extraction is useful, but overusing raw JsonPath strings across the framework can create maintenance problems. If a response structure is used frequently, consider mapping it to a POJO or centralizing extraction methods. This makes the code easier to refactor when the API contract changes.

Reusing Response Data

Reusing response data is common in API automation. A typical flow may create a user, extract the user ID, store it in scenario context, update the user, retrieve the user, and delete the user during cleanup. This pattern is powerful, but it must be managed carefully to avoid hidden dependencies and unreliable tests.

Create user
Extract userId
Store userId
Update user
Delete user

context.setUserId(id);

Scenario context should be scoped to the current scenario. If data is shared through static variables, parallel execution can become unsafe. Scenario A may overwrite a value used by Scenario B. A proper context object, dependency injection container, or scenario-scoped storage avoids this issue.

Deserialization

Deserialization means converting the response body into a Java object. Instead of manually extracting every field through JsonPath, a framework can map the response to a POJO. This improves readability and helps organize response data in typed Java classes.

UserResponse user =
    response.as(UserResponse.class);

After deserialization, the framework can use normal Java methods.

user.getName();
user.getEmail();

Object mapping is especially helpful for larger response bodies. It also makes validators cleaner because they can work with meaningful objects instead of repeated string paths. However, JsonPath remains useful for quick checks, dynamic structures, or partial validations. Mature frameworks often use both approaches.

Logging Requests and Responses

Logging is essential for troubleshooting API failures. REST Assured can log request details and response details. During development, logging everything can help understand the request and response flow. In CI, logging should be controlled so reports remain useful and sensitive data is not exposed.

given()
    .log().all();

response.then()
    .log().all();

Logs can reveal missing headers, incorrect endpoints, wrong request bodies, expired tokens, unexpected status codes, and malformed responses. However, logs may also contain tokens, passwords, personal data, or confidential fields. A good framework masks sensitive values and logs full details mainly when failures occur.

Request and Response Filters

REST Assured filters allow preprocessing, logging, and customization around requests and responses. Filters can be used to log all traffic, add common behavior, measure timing, integrate with reports, or capture request and response details for debugging. They are useful in enterprise frameworks because they centralize cross-cutting behavior.

given()
    .filter(new RequestLoggingFilter())
    .filter(new ResponseLoggingFilter());

Filters should be used carefully. They are powerful, but they can make behavior less obvious if too much logic is hidden inside them. Use them for common framework-level needs such as logging, reporting, or masking. Keep business-specific request behavior in API clients and builders where it is easier to understand.

Error Response Handling

Error response handling is as important as success response handling. APIs should return predictable errors when requests are invalid, unauthorized, forbidden, not found, duplicated, or blocked by business rules. A strong API automation suite validates these error contracts instead of testing only happy paths.

response.then()
    .statusCode(400)
    .body("error", equalTo("Invalid User"));

Negative scenarios should validate the status code, error code, message, field name, and any other contract fields that matter. For example, creating a user without an email should not just return any 400 response. It should return the expected validation error. This gives API consumers reliable behavior and helps developers catch regressions.

Request and Response Flow in Cucumber

In a Cucumber framework, request and response handling should be layered. The feature file describes the behavior. The step definition maps Gherkin steps to Java. The API client or service builds and sends the request. The request builder prepares payloads. REST Assured performs the HTTP operation. The response object is returned. The validator checks response details. Scenario context stores values when later steps need them. Reports show the final scenario outcome.

Feature File
Step Definition
API Client
Request Builder
REST Assured
REST API
Response
Validator
Report

This separation gives each layer a single responsibility. It also prevents feature files and step definitions from becoming overloaded. When an endpoint changes, update the API client. When a payload changes, update the request builder or POJO. When assertion rules change, update the validator. The feature file should change only when behavior changes.

Separating Request Building from Validation

Request building and response validation should not be mixed into one large step definition. Step definitions should remain thin. They should call reusable methods and pass meaningful data. The request builder should create request bodies. The API client should send requests. The validator should assert responses.

This design makes the framework easier to test and maintain. A builder can be reused by create, update, and negative scenarios. A validator can be reused by multiple scenarios that expect the same response contract. API clients can be reused by Cucumber tests, plain REST Assured tests, or setup utilities. Reuse is stronger when responsibilities are separated cleanly.

Common Mistakes in Request Handling

A common request-handling mistake is hardcoding URLs. If a test contains https://qa.example.com everywhere, changing environments becomes difficult. Base URLs should come from configuration. Another mistake is hardcoding tokens. Tokens expire, expose security risks, and make tests environment-dependent. Authentication should be dynamic or configured securely.

Another mistake is duplicating request code. Teams often copy a REST Assured block from one class to another and modify only the endpoint. Over time, this creates inconsistent headers, logging, authentication, and content types. Reusable request specifications and API clients prevent this duplication.

Some teams also build request bodies through string concatenation. This is fragile and can create invalid JSON. POJOs, maps, builders, templates, or external JSON files are usually safer. Choose the method that fits the scenario, but avoid messy manual string construction.

Common Mistakes in Response Handling

The most common response-handling mistake is validating only the status code. A status code is important, but it does not prove that the response body is correct. Tests should also validate meaningful fields, headers, schemas, response time, or business rules when applicable. Another mistake is ignoring negative responses. Error behavior is part of the API contract and should be tested.

Teams also sometimes extract values without checking whether they exist. If a response does not contain the expected ID, the next request may fail with a confusing error. Validate critical fields before using them. Another mistake is storing responses in global static variables, which can break parallel execution. Scenario-scoped storage is safer.

Best Practices

Centralize request creation using reusable Request Specifications whenever possible. Externalize base URI, credentials, tokens, and environment values. Use POJOs for request and response models when the structure is stable. Use maps, Doc Strings, or external JSON files where they improve readability. Validate status code, response body, headers, response time, and business rules based on the scenario purpose.

Extract reusable values into scenario context. Use logging during development and troubleshooting, but mask sensitive data. Reuse authentication and common request configuration. Separate request building, response validation, and business logic into dedicated classes. Keep Cucumber step definitions thin and readable.

Also design for failure analysis. When a test fails, the report should make it clear what request was sent, what response came back, and which validation failed. Good diagnostics save time for QA engineers and developers.

Enterprise Framework Architecture

In an enterprise Cucumber and REST Assured framework, request and response handling usually sits inside a modular architecture. Feature files describe behavior. Step definitions call API services. API services use request builders and request specifications. REST Assured sends requests. Response validators check contracts. Scenario context stores IDs and response objects. Reports capture the result.

Feature File
Step Definition
API Service
Request Builder
REST Assured
REST API
Response Validator
Scenario Context
Report

This architecture supports growth. New endpoints can be added by creating new API service methods. New request types can use builders. New validation rules can be added to validators. Authentication changes can be handled in one place. Reporting improvements can be added without rewriting every scenario.

Real-Time Example

Consider an order API. A scenario creates an order for an authenticated customer. The request needs a bearer token, content type, customer ID, product list, shipping address, and payment method. REST Assured sends the request. The response returns status code 201, an order ID, order status, total amount, and timestamps. The test extracts the order ID and stores it in scenario context.

A later step retrieves the order using the extracted ID. The framework validates that the order exists, belongs to the same customer, has the correct status, and contains the expected product details. After the scenario, an After hook may delete or cancel the test order. This flow depends on clean request construction, reliable response validation, and safe context handling.

If all this logic were written directly in one step definition, the test would become hard to maintain. With API clients, builders, validators, and context, the behavior remains understandable and the technical work remains reusable.

Interview-Ready Summary

Request handling involves constructing and sending HTTP requests with methods, headers, parameters, authentication, cookies, and request bodies. Response handling involves validating status codes, headers, response bodies, response time, content type, and extracting reusable data. REST Assured provides the Response object for accessing and validating all parts of an HTTP response.

In Cucumber frameworks, the feature file describes the API behavior, step definitions connect Gherkin to Java, API clients send requests, request builders prepare payloads, validators assert responses, and scenario context stores values used across steps. Enterprise frameworks centralize request construction, response validation, authentication, configuration, and logging into reusable components.

A strong interview answer should also mention that validating only the status code is weak, hardcoding URLs and tokens is risky, and duplicate request code should be replaced with reusable request specifications and API service classes.

Golden Rules

Build requests using reusable Request Specifications whenever possible. Validate more than just the status code by checking response body, headers, and business rules. Extract reusable response data into scenario context for later steps. Use POJOs instead of raw JSON strings whenever practical. Keep request building, response validation, and Cucumber step definitions separate for a clean and maintainable framework.

The golden idea is straightforward: request handling prepares and sends the API call, response handling proves the API behaved correctly, and Cucumber keeps the behavior readable. When these responsibilities are separated well, API automation becomes easier to understand, easier to maintain, and more reliable in real projects.