Request Building API Reference

public class HttpRequest {
    /**
     * Creates a new builder instance for constructing HTTP requests.
     *
     * @return new Builder instance
     */
    public static Builder builder();

    /**
     * @return the HTTP method (GET, POST, DELETE)
     */
    public HttpMethod method();

    /**
     * @return the complete URL including encoded query parameters
     */
    public String url();

    /**
     * @return the headers as a multi-value map
     */
    public Map<String, List<String>> headers();

    /**
     * @return the request body, or null if not set
     */
    public String body();

    /**
     * @return the form data fields, or empty map if not set
     * @since 1.10.0
     */
    public Map<String, String> formDataFields();

    /**
     * @return the form data files, or empty map if not set
     * @since 1.10.0
     */
    public Map<String, FormDataFile> formDataFiles();
}

public static class Builder {
    /**
     * Sets the HTTP method.
     *
     * @param method the HTTP method (GET, POST, DELETE)
     * @return this builder
     */
    public Builder method(HttpMethod method);

    /**
     * Sets the request URL.
     *
     * @param url the complete URL
     * @return this builder
     */
    public Builder url(String url);

    /**
     * Sets the request URL by combining a base URL and path.
     * Handles trailing/leading slashes automatically.
     *
     * @param baseUrl the base URL (e.g., "https://api.example.com")
     * @param path the path (e.g., "/users/123")
     * @return this builder
     */
    public Builder url(String baseUrl, String path);

    /**
     * Adds a header with one or more values.
     * If the header already exists, it will be replaced.
     *
     * @param name the header name
     * @param values one or more header values
     * @return this builder
     */
    public Builder addHeader(String name, String... values);

    /**
     * Adds multiple headers from a map.
     * Each entry results in a single-value header.
     *
     * @param headers map of header names to values
     * @return this builder
     */
    public Builder addHeaders(Map<String, String> headers);

    /**
     * Sets all headers, replacing any previously set.
     *
     * @param headers map of header names to lists of values
     * @return this builder
     */
    public Builder headers(Map<String, List<String>> headers);

    /**
     * Adds a query parameter to the URL.
     * Values are automatically URL-encoded.
     *
     * @param name the parameter name
     * @param value the parameter value
     * @return this builder
     */
    public Builder addQueryParam(String name, String value);

    /**
     * Adds multiple query parameters from a map.
     * Values are automatically URL-encoded.
     *
     * @param queryParams map of parameter names to values
     * @return this builder
     */
    public Builder addQueryParams(Map<String, String> queryParams);

    /**
     * Sets all query parameters, replacing any previously set.
     * Values are automatically URL-encoded.
     *
     * @param queryParams map of parameter names to values
     * @return this builder
     */
    public Builder queryParams(Map<String, String> queryParams);

    /**
     * Adds a form data field.
     * Cannot be used together with body().
     * Experimental API introduced in version 1.10.0.
     *
     * @param name the field name
     * @param value the field value
     * @return this builder
     */
    public Builder addFormDataField(String name, String value);

    /**
     * Sets all form data fields, replacing any previously set.
     * Cannot be used together with body().
     * Experimental API introduced in version 1.10.0.
     *
     * @param formDataFields map of field names to values
     * @return this builder
     */
    public Builder formDataFields(Map<String, String> formDataFields);

    /**
     * Adds a form data file for multipart upload.
     * Cannot be used together with body().
     * Experimental API introduced in version 1.10.0.
     *
     * @param name the field name
     * @param fileName the file name
     * @param contentType the content type (e.g., "image/png")
     * @param content the file content as bytes
     * @return this builder
     */
    public Builder addFormDataFile(String name, String fileName, String contentType, byte[] content);

    /**
     * Sets all form data files, replacing any previously set.
     * Cannot be used together with body().
     * Experimental API introduced in version 1.10.0.
     *
     * @param formDataFiles map of field names to FormDataFile objects
     * @return this builder
     */
    public Builder formDataFiles(Map<String, FormDataFile> formDataFiles);

    /**
     * Sets the request body.
     * Cannot be used together with formDataFields() or formDataFiles().
     *
     * @param body the request body as a string
     * @return this builder
     */
    public Builder body(String body);

    /**
     * Builds the HttpRequest instance.
     *
     * @return the constructed HttpRequest
     * @throws IllegalArgumentException if both body and form data are specified,
     *         or if required fields are missing
     */
    public HttpRequest build();
}

public enum HttpMethod {
    GET,
    POST,
    DELETE
}

/**
 * Represents a file for multipart form data upload.
 * Experimental API introduced in version 1.10.0.
 */
public class FormDataFile {
    /**
     * Creates a new FormDataFile.
     *
     * @param fileName the file name
     * @param contentType the MIME content type
     * @param content the file content as bytes
     */
    public FormDataFile(String fileName, String contentType, byte[] content);

    /**
     * @return the file name
     */
    public String fileName();

    /**
     * @return the MIME content type
     */
    public String contentType();

    /**
     * @return the file content as bytes
     */
    public byte[] content();
}