⚙️ URI Structure, Query Filtering & Form Transport Mechanics
Modern RESTful APIs decouple resource locations, query criteria, and payload representations across different segments of the HTTP request. Path parameters identify specific resources hierarchically (such as pointing to a tenant or unique entity ID like /institutions/{instId}/students/{studentId}). Query parameters control state filtering, pagination, sorting, and searching across collections (e.g., ?status=ENROLLED&limit=20&sort=desc). Concurrently, form parameters package HTML and OAuth2 form data inside the request body using application/x-www-form-urlencoded. Rather than manually concatenating raw strings with risk of malformed URI encoding, REST Assured provides dedicated DSL methods—pathParam(), queryParam(), and formParam()—that handle template variable interpolation, multi-value list expansion, and RFC 3986 percent-encoding automatically.
HTTP PARAMETER WIRE ANATOMY & REST ASSURED DSL ROUTING:
https://api.nikita-infotech.com/v1/institutions/{instId}/departments/{deptCode}/students/{id}?status=ACTIVE&limit=10
└─────────────┬──────────────┘└──┬──┘└──────────────────────┬──────────────────────────────┘└─────────┬──────────┘
│ │ │ │
BASE URI TARGET BASE PATH PATH PARAMETERS QUERY PARAMETERS
.baseUri(...) .basePath(...) .pathParam("instId", ...) .queryParam("status", ...)
.pathParam("deptCode", ...) .queryParam("limit", ...)
.pathParam("id", ...)
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ PARAMETER CLASSIFICATION MATRIX: │
├─────────────────────┬──────────────────────────────┬────────────────────────────┬────────────────────────────┤
│ PARAMETER TYPE │ INJECTION METHOD │ WIRE LOCATION │ PRIMARY OPERATIONAL ROLE │
├─────────────────────┼──────────────────────────────┼────────────────────────────┼────────────────────────────┤
│ Path Parameter │ .pathParam("key", value) │ Target URL Path Segments │ Hierarchical identity │
│ Query Parameter │ .queryParam("key", value) │ URL Query String (?key=val)│ Filtering, pagination, sort│
│ Form Parameter │ .formParam("key", value) │ HTTP Entity Body Payload │ application/x-www-form-url │
│ Matrix Parameter │ .matrixParam("key", value) │ Path Semicolons (;k=v) │ Legacy matrix path context │
└─────────────────────┴──────────────────────────────┴────────────────────────────┴────────────────────────────┘
{paramName}). Demonstrates single parameter injection via pathParam() and bulk multi-parameter injection using a Java Map via pathParams().
package com.nikita.restassured.params;
import org.testng.annotations.Test;
import java.util.HashMap;
import java.util.Map;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
public class NamedPathParamTest {
private static final String BASE_URI = "https://staging-api.nikita-infotech.com/v1";
@Test(description = "Inject single named path parameter into template URI")
public void testSinglePathParam() {
given()
.baseUri(BASE_URI)
// Binds dynamic token {studentId} to STU-88219:
.pathParam("studentId", "STU-88219")
.when()
.get("/students/{studentId}")
.then()
.statusCode(200)
.body("data.id", equalTo("STU-88219"));
System.out.println("[✔] Resolved single path param: /students/STU-88219");
}
@Test(description = "Inject multiple named path parameters simultaneously via Map")
public void testBulkPathParamsViaMap() {
Map<String, Object> hierarchyParams = new HashMap<>();
hierarchyParams.put("institutionId", "PUNE-CAMPUS-01");
hierarchyParams.put("departmentCode", "CS");
hierarchyParams.put("studentId", "STU-88219");
given()
.baseUri(BASE_URI)
// Binds all map entries to matching {tokens} in the URL:
.pathParams(hierarchyParams)
.when()
.get("/institutions/{institutionId}/departments/{departmentCode}/students/{studentId}")
.then()
.statusCode(200)
.body("data.id", equalTo("STU-88219"))
.body("data.department", equalTo("CS"));
System.out.println("[✔] Resolved hierarchical path parameters cleanly via pathParams(Map).");
}
}
get(), delete()). Shows how unnamed parameters map in strict index order to curly braces without explicit pathParam() declarations.
package com.nikita.restassured.params;
import org.testng.annotations.Test;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
public class UnnamedPathParamTest {
@Test(description = "Demonstrate positional unnamed path parameter substitution")
public void testUnnamedPositionalPathParams() {
String institution = "PUNE-CAMPUS-01";
String department = "CS";
String studentId = "STU-88219";
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
.when()
// Arguments passed to get(...) map positionally in index order:
// 1st arg replaces 1st {}, 2nd arg replaces 2nd {}, etc.
.get("/institutions/{inst}/departments/{dept}/students/{id}",
institution, department, studentId)
.then()
.statusCode(200)
.body("data.id", equalTo(studentId));
System.out.println("[✔] Positional parameters interpolated successfully without explicit pathParam().");
}
}
queryParam(), bulk injection via Java Map using queryParams(), and validating returned collections.
package com.nikita.restassured.params;
import org.testng.annotations.Test;
import java.util.HashMap;
import java.util.Map;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.*;
public class QueryParamTest {
private static final String BASE_URI = "https://staging-api.nikita-infotech.com/v1";
@Test(description = "Filter catalog using chained single queryParam calls")
public void testSingleQueryParams() {
given()
.baseUri(BASE_URI)
.queryParam("academicTrack", "ENTERPRISE_AUTOMATION")
.queryParam("status", "ENROLLED")
.queryParam("limit", 15)
.queryParam("page", 1)
.when()
.get("/students")
.then()
.statusCode(200)
.body("pagination.pageSize", equalTo(15))
.body("data.every { it.academicTrack == 'ENTERPRISE_AUTOMATION' }", is(true));
System.out.println("[✔] Chained query parameters filtered student catalog successfully.");
}
@Test(description = "Filter catalog using bulk query parameters via Map")
public void testBulkQueryParamsViaMap() {
Map<String, Object> filterCriteria = new HashMap<>();
filterCriteria.put("academicTrack", "ENTERPRISE_AUTOMATION");
filterCriteria.put("creditsMin", 4);
filterCriteria.put("sortBy", "createdAt");
filterCriteria.put("order", "desc");
given()
.baseUri(BASE_URI)
.queryParams(filterCriteria)
.when()
.get("/students")
.then()
.statusCode(200)
.body("data.size()", greaterThan(0));
System.out.println("[✔] Injected query criteria map cleanly into request URL.");
}
}
queryParam() to generate repeat parameters (?track=A&track=B) or comma-separated lists.
package com.nikita.restassured.params;
import org.testng.annotations.Test;
import java.util.Arrays;
import java.util.List;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.greaterThan;
public class MultiValueQueryParamTest {
@Test(description = "Inject multi-value query parameter via Java List (Generates repeat keys)")
public void testMultiValueQueryUsingList() {
List<String> targetTracks = Arrays.asList(
"ENTERPRISE_AUTOMATION",
"FULLSTACK_SDET",
"CLOUD_DEVOPS_QA"
);
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
// Passing a List to queryParam generates multiple repeat query keys:
// ?track=ENTERPRISE_AUTOMATION&track=FULLSTACK_SDET&track=CLOUD_DEVOPS_QA
.queryParam("track", targetTracks)
.when()
.get("/students")
.then()
.statusCode(200)
.body("data.size()", greaterThan(0));
System.out.println("[✔] Multi-value list parameter expanded into repeat query keys.");
}
@Test(description = "Inject multi-value query parameter using varargs syntax")
public void testMultiValueQueryUsingVarargs() {
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
// Passing varargs: queryParam("key", val1, val2, val3)
.queryParam("role", "STUDENT", "INSTRUCTOR", "MENTOR")
.when()
.get("/users")
.then()
.statusCode(200);
System.out.println("[✔] Multi-value varargs expanded to ?role=STUDENT&role=INSTRUCTOR&role=MENTOR.");
}
}
%20) and special characters, and how to use urlEncodingEnabled(false) when testing raw or pre-encoded strings.
package com.nikita.restassured.params;
import org.testng.annotations.Test;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
public class UrlEncodingGovernanceTest {
@Test(description = "Automatic RFC 3986 URL encoding of special characters and spaces")
public void testAutomaticUrlEncoding() {
String searchQuery = "Automation & SDET Masterclass + Core Java";
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
// REST Assured automatically converts spaces to %20 and & to %26:
.queryParam("query", searchQuery)
.when()
.get("/courses/search")
.then()
.statusCode(200)
.body("echoedQuery", equalTo(searchQuery));
System.out.println("[✔] Special characters encoded automatically by REST Assured.");
}
@Test(description = "Disabling automatic URL encoding for already encoded or raw values")
public void testDisableUrlEncoding() {
// Pre-encoded string containing %2F (encoded slash)
String preEncodedParam = "batches%2Fpune-west-01";
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
// Disable URL encoding so %2F is not re-encoded into %252F!
.urlEncodingEnabled(false)
.queryParam("batchPath", preEncodedParam)
.when()
.get("/batches/resolve")
.then()
.statusCode(200);
System.out.println("[✔] Bypassed re-encoding using urlEncodingEnabled(false).");
}
}
application/x-www-form-urlencoded forms using formParam(). Demonstrates authenticating against OAuth2 token endpoints with client credentials.
package com.nikita.restassured.params;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import java.util.HashMap;
import java.util.Map;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;
import static org.hamcrest.Matchers.notNullValue;
public class FormParamTest {
@Test(description = "Submit OAuth2 token credentials via formParam() in request body")
public void testOAuthTokenViaFormParams() {
given()
.baseUri("https://auth.nikita-infotech.com")
// formParam() automatically sets Content-Type: application/x-www-form-urlencoded
.contentType(ContentType.URLENC.withCharset("UTF-8"))
.formParam("grant_type", "client_credentials")
.formParam("client_id", "automation-worker-pune")
.formParam("client_secret", "Secret#Enterprise2026Key")
.formParam("scope", "students.read students.write")
.when()
.post("/oauth/v2/token")
.then()
.statusCode(200)
.contentType(ContentType.JSON)
.body("token_type", equalTo("Bearer"))
.body("access_token", notNullValue());
System.out.println("[✔] Form parameters posted in body; OAuth Bearer token minted successfully.");
}
@Test(description = "Submit bulk form parameters via Java Map")
public void testBulkFormParamsViaMap() {
Map<String, Object> loginForm = new HashMap<>();
loginForm.put("username", "sdet.lead@nikita-infotech.com");
loginForm.put("password", "Pass#Pune2026");
loginForm.put("rememberMe", "true");
given()
.baseUri("https://staging-api.nikita-infotech.com")
.formParams(loginForm)
.when()
.post("/v1/session/login")
.then()
.statusCode(200);
System.out.println("[✔] Bulk form parameters processed cleanly.");
}
}
package com.nikita.restassured.params;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import java.util.UUID;
import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.*;
public class CombinedParametersTest {
@Test(description = "Combine path, query, and header parameters in a single fluid call")
public void testUnifiedParameterCall() {
String correlationId = UUID.randomUUID().toString();
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
// 1. Path Parameters: Target specific student and course domain
.pathParam("department", "COMPUTER_SCIENCE")
.pathParam("studentId", "STU-88219")
// 2. Query Parameters: Filter, sort, and paginate grade history
.queryParam("semester", "FALL_2026")
.queryParam("minCredits", 3)
.queryParam("sort", "grade:desc")
// 3. Header Parameters: Authentication and distributed tracing
.header("Authorization", "Bearer eyJhbGciOiJIUzI1Ni...")
.header("X-Correlation-ID", correlationId)
.accept(ContentType.JSON)
.log().ifValidationFails()
.when()
.get("/departments/{department}/students/{studentId}/grades")
.then()
.log().ifValidationFails()
.statusCode(200)
.contentType(ContentType.JSON)
.body("status", equalTo("SUCCESS"))
.body("studentId", equalTo("STU-88219"))
.body("records.size()", greaterThan(0));
System.out.println("[✔] Multi-parameter request resolved and validated cleanly.");
}
}
IllegalArgumentException (e.g. declaring {studentId} but binding id), query string concatenation bugs, and missing values.
package com.nikita.restassured.params;
import org.testng.annotations.Test;
import static io.restassured.RestAssured.given;
public class ParameterDebuggingTest {
// ==========================================================================
// COMMON ERROR: java.lang.IllegalArgumentException:
// You have not defined what the path parameter 'studentId' is!
// CAUSE: URL defines /students/{studentId}, but code called .pathParam("id", ...)
// ==========================================================================
@Test(expectedExceptions = IllegalArgumentException.class,
description = "Demonstrate exception thrown when path token is not resolved")
public void testUnresolvedPathParameterThrowsException() {
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
// BUG: Token in URL is {studentId}, but parameter declared as "id":
.pathParam("id", "STU-88219")
.when()
.get("/students/{studentId}") // Throws IllegalArgumentException!
.then()
.statusCode(200);
}
// ==========================================================================
// BEST PRACTICE: INSPECTING GENERATED URL BEFORE DISPATCH
// Using log().all() or log().uri() to inspect the resolved URI string
// ==========================================================================
@Test(description = "Verify resolved URI structure in console log")
public void testVerifyResolvedUri() {
given()
.baseUri("https://staging-api.nikita-infotech.com/v1")
.pathParam("studentId", "STU-88219")
.queryParam("status", "ACTIVE")
.log().uri() // Prints the final resolved URI to stdout
.when()
.get("/students/{studentId}")
.then()
.statusCode(200);
}
}
REST ASSURED PARAMETER INJECTION SPECIFICATION MATRIX:
┌─────────────────────────┬──────────────────────────────┬──────────────────┬───────────────────────────────┐
│ PARAMETER TYPE │ DSL METHOD SIGNATURE │ ARGUMENT TYPES │ PRIMARY OPERATIONAL PURPOSE │
├─────────────────────────┼──────────────────────────────┼──────────────────┼───────────────────────────────┤
│ Named Path Param │ .pathParam(name, value) │ String, Object │ Binds named {token} in URI │
│ Bulk Path Params │ .pathParams(Map<String, ?>) │ Map of Key-Values│ Bulk binds multiple path token│
│ Unnamed Positional Param│ .get("/path/{a}/{b}", a, b) │ Varargs Object │ Position-based path mapping │
│ Single Query Param │ .queryParam(name, value) │ String, Object │ Injects ?key=value filter │
│ Bulk Query Params │ .queryParams(Map<String, ?>) │ Map of Key-Values│ Injects multi-key query map │
│ Multi-Value Query (List)│ .queryParam(name, List) │ Collection<?> │ Expands to ?key=v1&key=v2 │
│ Multi-Value (Varargs) │ .queryParam(name, v1, v2) │ Varargs Object │ Expands to ?key=v1&key=v2 │
│ Single Form Param │ .formParam(name, value) │ String, Object │ Injects into URL-encoded body │
│ Bulk Form Params │ .formParams(Map<String, ?>) │ Map of Key-Values│ Submits complete form map │
│ Matrix Parameter │ .matrixParam(name, value) │ String, Object │ Semicolon path params (;k=v) │
│ Disable URL Encoding │ .urlEncodingEnabled(false) │ Boolean Flag │ Bypasses percent-encoding │
├─────────────────────────┴──────────────────────────────┴──────────────────┴───────────────────────────────┤
│ TOP 5 PARAMETER INJECTION BEST PRACTICES: │
│ 1. Match path tokens exactly: Verify {studentId} in the URI matches .pathParam("studentId"). │
│ 2. Use Map arguments for bulk params: Pass pre-built Maps into .pathParams() and .queryParams(). │
│ 3. Pass Java Lists for multi-value queries: Let REST Assured expand repeat query keys automatically. │
│ 4. Use formParam() for OAuth token requests: Automatically sets application/x-www-form-urlencoded. │
│ 5. Use log().uri() during debugging: Inspect the final resolved URL to verify encoding and parameters. │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘