Response Specifications

When testing APIs with REST Assured, you often repeat the same checks across multiple requests—like verifying the status code, headers, and content type. Instead of writing the same code again and again, you can use Response Specifications to reuse these validations.

In this tutorial, you will learn:

What Response Specifications are.
How to create and reuse a response specification.
How to customize response specifications.

What is a Response Specification?

A Response Specification in REST Assured is a template that defines the expected structure of an API response. It allows you to:

Avoid repeating the same checks (like status code or headers).
Make your tests cleaner and easier to maintain.
Reuse the same response checks across multiple tests.

Without Response Specification (Repetitive Code)

Here is an example where we repeat the same checks in multiple tests:

Java

Copy

// First Test - Validate User Details
given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .statusCode(200)
    .header("Content-Type", "application/json; charset=utf-8")
    .body("name", equalTo("Book 1"));

// Second Test - Validate Post Details
given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .statusCode(200)
    .header("Content-Type", "application/json; charset=utf-8")
    .body("language", notNullValue());

Problem: You are repeating the same checks (statusCode, Content-Type).

With Response Specification (Reusable Code)

We can reuse the common checks using a Response Specification.

Creating and Using Response Specifications

Create a Response Specification

Java

Copy

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

ResponseSpecification commonSpec = new ResponseSpecBuilder()
    .expectStatusCode(200)                          // Always expect 200 OK
    .expectHeader("Content-Type", "application/json; charset=utf-8")  // Ensure JSON response
    .build();

Use Response Specification in Multiple Tests

Now, we can reuse commonSpec in multiple tests.

Java

Copy

// Validate User Details
given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .spec(commonSpec)                  // Reuse the common response spec
    .body("name", equalTo("Book 1"));

// Validate Post Details
given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .spec(commonSpec)                  // Use the same response spec
    .body("language", notNullValue());

Benefit: Less code duplication and easier to maintain.

Customizing Response Specifications

You can customize response specifications to fit different scenarios.

Validate JSON Response with Dynamic Fields

Example: Create a custom response specification for validating a user.

Java

Copy

ResponseSpecification bookSpec = new ResponseSpecBuilder()
    .expectStatusCode(200)
    .expectHeader("Content-Type", "application/json; charset=utf-8")
    .expectBody("name", notNullValue())
    .expectBody("publisher", containsString("ABC"))
    .build();

given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .spec(bookSpec);

Validate XML Response

REST Assured also works with XML.

Example: Create a response specification for XML responses.

Java

Copy

ResponseSpecification xmlSpec = new ResponseSpecBuilder()
    .expectStatusCode(200)
    .expectContentType("application/xml")
    .expectBody("book.name", equalTo("Book 1"))
    .build();

given()
    .accept("application/xml")
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .spec(xmlSpec);

Validate Error Responses (400, 404, etc.)

If you expect an error response, you can create a separate specification.

Example: Response Specification for a 404 Not Found.

Java

Copy

ResponseSpecification notFoundSpec = new ResponseSpecBuilder()
    .expectStatusCode(404)
    .expectBody("error", equalTo("User not found"))
    .build();

given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/123")
    .then()
    .spec(notFoundSpec);

Combining Multiple Response Specifications

You can combine multiple specifications by chaining them together.

Example: Validate common and custom checks.

Java

Copy

ResponseSpecification commonSpec = new ResponseSpecBuilder()
    .expectStatusCode(200)
    .expectHeader("Content-Type", "application/json; charset=utf-8")
    .build();

ResponseSpecification bookSpec = new ResponseSpecBuilder()
    .expectBody("name", notNullValue())
    .expectBody("publisher", containsString("ABC"))
    .build();

given()
    .when()
    .get("http://192.xxx.xx.xxx:8080/books/20250401")
    .then()
    .spec(commonSpec)  // Common checks
    .spec(bookSpec);   // Book-specific checks

Global Response Specification (Applies to All Requests)

If you want to apply a specification to every request, you can set it globally.

Example: Apply a global response specification.

Java

Copy

import static io.restassured.RestAssured.*;

@BeforeAll
public static void setup() {
    ResponseSpecification globalSpec = new ResponseSpecBuilder()
        .expectStatusCode(200)
        .expectHeader("Content-Type", "application/json; charset=utf-8")
        .build();
    RestAssured.responseSpecification = globalSpec; // Apply globally
}

@Test
public void testBook() {
    given()
        .when()
        .get("http://192.xxx.xx.xxx:8080/books/20250401")
        .then()
        .body("name", equalTo("book 1"));
}