Request Building

/**
 * Start building the request specification (same as with())
 * @return A request specification for fluent configuration
 */
static RequestSpecification given();

/**
 * Start building the request specification (same as given()) 
 * @return A request specification for fluent configuration 
 */
static RequestSpecification with();

/**
 * Start building DSL expression for immediate request sending
 * @return A request sender interface
 */
static RequestSender when();

/**
 * Create request specification from existing specifications
 * @param requestSpecification Pre-configured request specification
 * @param responseSpecification Pre-configured response specification
 * @return Request sender with both specifications applied
 */
static RequestSender given(RequestSpecification requestSpecification, ResponseSpecification responseSpecification);

/**
 * Create request specification from existing request specification only
 * @param requestSpecification Pre-configured request specification
 * @return Request specification with existing spec applied
 */
static RequestSpecification given(RequestSpecification requestSpecification);

// Basic fluent API
given()
    .header("Accept", "application/json")
    .queryParam("limit", 10)
.when()
    .get("/users")
.then()
    .statusCode(200);

// Immediate request (no additional parameters)
when()
    .get("/health")
.then()
    .statusCode(200);

// Using pre-built specifications
RequestSpecification baseSpec = new RequestSpecBuilder()
    .setBaseUri("https://api.example.com")
    .setContentType(ContentType.JSON)
    .build();

given(baseSpec)
    .queryParam("filter", "active")
.when()
    .get("/users");

interface RequestSpecification {
    /**
     * Set request body as string
     * @param body The string body content
     * @return Updated request specification
     */
    RequestSpecification body(String body);
    
    /**
     * Set request body as byte array
     * @param body The byte array body content
     * @return Updated request specification
     */
    RequestSpecification body(byte[] body);
    
    /**
     * Set request body from file
     * @param file The file to read body content from
     * @return Updated request specification
     */
    RequestSpecification body(File file);
    
    /**
     * Set request body from input stream
     * @param stream The input stream to read body content from
     * @return Updated request specification
     */
    RequestSpecification body(InputStream stream);
    
    /**
     * Set request body from Java object (will be serialized to JSON/XML)
     * @param object The object to serialize as request body
     * @return Updated request specification
     */
    RequestSpecification body(Object object);
    
    /**
     * Set request body from object with specific object mapper
     * @param object The object to serialize
     * @param mapper The object mapper to use for serialization
     * @return Updated request specification
     */
    RequestSpecification body(Object object, ObjectMapper mapper);
    
    /**
     * Set request body from object with specific object mapper type
     * @param object The object to serialize
     * @param mapperType The type of object mapper to use
     * @return Updated request specification
     */
    RequestSpecification body(Object object, ObjectMapperType mapperType);
}

// String body
given()
    .body("{\"name\":\"John\",\"email\":\"john@example.com\"}")
    .contentType(ContentType.JSON)
.when()
    .post("/users");

// Object body (auto-serialized to JSON)
User user = new User("John", "john@example.com");
given()
    .body(user)
    .contentType(ContentType.JSON)
.when()
    .post("/users");

// File body
given()
    .body(new File("user-data.json"))
    .contentType(ContentType.JSON)
.when()
    .post("/users");

interface RequestSpecification {
    /**
     * Add a request parameter (query param for GET, form param for POST)
     * @param parameterName The parameter name
     * @param parameterValues The parameter values
     * @return Updated request specification
     */
    RequestSpecification param(String parameterName, Object... parameterValues);
    
    /**
     * Add multiple request parameters
     * @param parametersMap Map of parameter names to values
     * @return Updated request specification
     */
    RequestSpecification params(Map<String, ?> parametersMap);
    
    /**
     * Add a query parameter
     * @param parameterName The query parameter name
     * @param parameterValues The query parameter values
     * @return Updated request specification
     */
    RequestSpecification queryParam(String parameterName, Object... parameterValues);
    
    /**
     * Add multiple query parameters
     * @param parametersMap Map of query parameter names to values
     * @return Updated request specification
     */
    RequestSpecification queryParams(Map<String, ?> parametersMap);
    
    /**
     * Add a form parameter
     * @param parameterName The form parameter name
     * @param parameterValues The form parameter values
     * @return Updated request specification
     */
    RequestSpecification formParam(String parameterName, Object... parameterValues);
    
    /**
     * Add multiple form parameters
     * @param parametersMap Map of form parameter names to values
     * @return Updated request specification
     */
    RequestSpecification formParams(Map<String, ?> parametersMap);
    
    /**
     * Add a path parameter for URL template substitution
     * @param parameterName The path parameter name
     * @param parameterValue The path parameter value
     * @return Updated request specification
     */
    RequestSpecification pathParam(String parameterName, Object parameterValue);
    
    /**
     * Add multiple path parameters for URL template substitution
     * @param parametersMap Map of path parameter names to values
     * @return Updated request specification
     */
    RequestSpecification pathParams(Map<String, Object> parametersMap);
}

// Query parameters
given()
    .queryParam("page", 1)
    .queryParam("size", 20)
    .queryParam("sort", "name", "asc")
.when()
    .get("/users");

// Form parameters
given()
    .formParam("username", "john")
    .formParam("password", "secret")
.when()
    .post("/login");

// Path parameters
given()
    .pathParam("userId", 123)
    .pathParam("postId", 456)
.when()
    .get("/users/{userId}/posts/{postId}");

// Multiple parameters with map
Map<String, Object> queryParams = new HashMap<>();
queryParams.put("status", "active");
queryParams.put("role", "admin");
given()
    .queryParams(queryParams)
.when()
    .get("/users");

interface RequestSpecification {
    /**
     * Add a header to the request
     * @param headerName The header name
     * @param headerValue The header value
     * @return Updated request specification
     */
    RequestSpecification header(String headerName, Object headerValue);
    
    /**
     * Add multiple headers to the request
     * @param firstHeaderName First header name
     * @param firstHeaderValue First header value  
     * @param headerNameValuePairs Additional header name-value pairs
     * @return Updated request specification
     */
    RequestSpecification headers(String firstHeaderName, Object firstHeaderValue, Object... headerNameValuePairs);
    
    /**
     * Add headers from a map
     * @param headers Map of header names to values
     * @return Updated request specification
     */
    RequestSpecification headers(Map<String, ?> headers);
    
    /**
     * Add headers from Headers object
     * @param headers Headers object containing multiple headers
     * @return Updated request specification
     */
    RequestSpecification headers(Headers headers);
}

// Single header
given()
    .header("Accept", "application/json")
    .header("Authorization", "Bearer token123")
.when()
    .get("/protected");

// Multiple headers
given()
    .headers("Accept", "application/json", 
             "User-Agent", "REST-Assured/5.5.2",
             "X-API-Version", "v1")
.when()
    .get("/api/data");

// Headers from map
Map<String, String> headers = new HashMap<>();
headers.put("Accept", "application/json");
headers.put("Content-Type", "application/json");
given()
    .headers(headers)
.when()
    .post("/api/data");

interface RequestSpecification {
    /**
     * Add a cookie to the request
     * @param cookieName The cookie name
     * @param cookieValue The cookie value
     * @return Updated request specification
     */
    RequestSpecification cookie(String cookieName, Object cookieValue);
    
    /**
     * Add a detailed cookie to the request
     * @param cookie Cookie object with full cookie attributes
     * @return Updated request specification
     */
    RequestSpecification cookie(Cookie cookie);
    
    /**
     * Add multiple cookies to the request
     * @param firstCookieName First cookie name
     * @param firstCookieValue First cookie value
     * @param cookieNameValuePairs Additional cookie name-value pairs
     * @return Updated request specification
     */
    RequestSpecification cookies(String firstCookieName, Object firstCookieValue, Object... cookieNameValuePairs);
    
    /**
     * Add cookies from a map
     * @param cookies Map of cookie names to values
     * @return Updated request specification
     */
    RequestSpecification cookies(Map<String, ?> cookies);
    
    /**
     * Add cookies from Cookies object
     * @param cookies Cookies object containing multiple cookies
     * @return Updated request specification
     */
    RequestSpecification cookies(Cookies cookies);
}

interface RequestSpecification {
    /**
     * Set the content type header
     * @param contentType The content type to set
     * @return Updated request specification
     */
    RequestSpecification contentType(ContentType contentType);
    
    /**
     * Set the content type header as string
     * @param contentType The content type string
     * @return Updated request specification
     */
    RequestSpecification contentType(String contentType);
    
    /**
     * Set the accept header
     * @param mediaTypes The media types to accept
     * @return Updated request specification
     */
    RequestSpecification accept(ContentType mediaTypes);
    
    /**
     * Set the accept header as string
     * @param mediaTypes The media types to accept as string
     * @return Updated request specification
     */
    RequestSpecification accept(String mediaTypes);
}

interface RequestSpecification {
    /**
     * Access authentication specification
     * @return Authentication specification for configuring auth
     */
    AuthenticationSpecification auth();
}

interface AuthenticationSpecification {
    /**
     * Use HTTP basic authentication
     * @param userName The username
     * @param password The password
     * @return Updated request specification
     */
    RequestSpecification basic(String userName, String password);
    
    /**
     * Use preemptive HTTP basic authentication
     * @return Preemptive auth specification
     */
    PreemptiveAuthSpec preemptive();
    
    /**
     * Use HTTP digest authentication
     * @param userName The username
     * @param password The password
     * @return Updated request specification
     */
    RequestSpecification digest(String userName, String password);
    
    /**
     * Use form-based authentication
     * @param userName The username
     * @param password The password
     * @return Updated request specification
     */
    RequestSpecification form(String userName, String password);
    
    /**
     * Use OAuth 1.0 authentication
     * @param consumerKey OAuth consumer key
     * @param consumerSecret OAuth consumer secret
     * @param accessToken OAuth access token
     * @param secretToken OAuth secret token
     * @return Updated request specification
     */
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
    
    /**
     * Use OAuth 2.0 authentication
     * @param accessToken OAuth 2.0 access token
     * @return Updated request specification
     */
    RequestSpecification oauth2(String accessToken);
    
    /**
     * Use certificate-based authentication
     * @param certURL Path to certificate
     * @param password Certificate password
     * @return Updated request specification
     */
    RequestSpecification certificate(String certURL, String password);
    
    /**
     * Disable authentication for this request
     * @return Updated request specification
     */
    RequestSpecification none();
}

interface RequestSpecification {
    /**
     * Add a multipart form data part
     * @param controlName The form control name
     * @param filename The filename
     * @param data The file data
     * @param mimeType The MIME type of the data
     * @return Updated request specification
     */
    RequestSpecification multiPart(String controlName, String filename, byte[] data, String mimeType);
    
    /**
     * Add a multipart form data part from file
     * @param controlName The form control name
     * @param file The file to upload
     * @return Updated request specification
     */
    RequestSpecification multiPart(String controlName, File file);
    
    /**
     * Add a multipart form data part from file with MIME type
     * @param controlName The form control name
     * @param file The file to upload
     * @param mimeType The MIME type of the file
     * @return Updated request specification
     */
    RequestSpecification multiPart(String controlName, File file, String mimeType);
    
    /**
     * Add a multipart form data specification
     * @param multiPartSpecification The multipart specification
     * @return Updated request specification
     */
    RequestSpecification multiPart(MultiPartSpecification multiPartSpecification);
}

interface RequestSpecification {
    /**
     * Apply configuration to this request
     * @param config The REST Assured configuration
     * @return Updated request specification
     */
    RequestSpecification config(RestAssuredConfig config);
    
    /**
     * Apply a specification to this request
     * @param requestSpecificationToMerge The specification to merge
     * @return Updated request specification
     */
    RequestSpecification spec(RequestSpecification requestSpecificationToMerge);
    
    /**
     * Add a filter to this request
     * @param filter The filter to add
     * @return Updated request specification
     */
    RequestSpecification filter(Filter filter);
    
    /**
     * Add multiple filters to this request
     * @param filters The filters to add
     * @return Updated request specification  
     */
    RequestSpecification filters(List<Filter> filters);
    
    /**
     * Add filters to this request
     * @param filter The first filter
     * @param additionalFilters Additional filters
     * @return Updated request specification
     */
    RequestSpecification filters(Filter filter, Filter... additionalFilters);
}

// Main request specification interface
interface RequestSpecification extends RequestSender, RequestSenderOptions {
    // All methods listed above are part of this interface
}

// Request sender interface for HTTP method execution
interface RequestSender {
    Response get(String path, Object... pathParameters);
    Response post(String path, Object... pathParameters);
    Response put(String path, Object... pathParameters);
    Response delete(String path, Object... pathParameters);
    Response head(String path, Object... pathParameters);
    Response patch(String path, Object... pathParameters);
    Response options(String path, Object... pathParameters);
    Response request(Method method, String path, Object... pathParameters);
    Response request(String method, String path, Object... pathParameters);
}

// Content type enumeration
enum ContentType {
    JSON("application/json"),
    XML("application/xml"),
    HTML("text/html"),
    TEXT("text/plain"),
    URLENC("application/x-www-form-urlencoded"),
    MULTIPART("multipart/form-data"),
    BINARY("application/octet-stream"),
    ANY("*/*");
    
    String toString();
    String getContentTypeStrings();
    boolean matches(String contentType);
}

// Multipart specification
interface MultiPartSpecification {
    String getControlName();
    String getMimeType();
    String getFileName();
    Object getContent();
}