Package io.mochaapi.client

Class ApiRequest

java.lang.Object
io.mochaapi.client.ApiRequest
public class ApiRequest extends Object
Represents a configurable HTTP request with chainable methods. Allows building requests step by step with headers, query parameters, and body.

Example usage:

 ApiResponse response = client.get("https://api.example.com/data")
     .header("Authorization", "Bearer token123")
     .query("page", 1)
     .query("limit", 10)
     .body(requestData)
     .execute();
Since:
1.0.0

  • Constructor Details

    • ApiRequest

      public ApiRequest(String url, String method, ApiClient client)
      Creates a new API request with the specified URL and HTTP method. This constructor is used internally by ApiClient.
      Parameters:
      url - the target URL
      method - the HTTP method (GET, POST, PUT, DELETE, PATCH)
      client - the ApiClient instance

    • ApiRequest

      public ApiRequest(String url, String method)
      Creates a new API request with the specified URL and HTTP method. This constructor is used by the static Api class for backward compatibility.
      Parameters:
      url - the target URL
      method - the HTTP method (GET, POST, PUT, DELETE, PATCH)

  • Method Details

    • getSecurityConfig

      public SecurityConfig getSecurityConfig()
      Gets the security configuration from the associated client. Uses production-safe defaults if no client is associated.
      Returns:
      SecurityConfig instance

    • header

      public ApiRequest header(String name, String value)
      Adds a header to the request.
      Parameters:
      name - the header name
      value - the header value
      Returns:
      this request for chaining
      Throws:
      IllegalArgumentException - if name or value is null

    • query

      public ApiRequest query(String name, Object value)
      Adds a query parameter to the request.
      Parameters:
      name - the parameter name
      value - the parameter value
      Returns:
      this request for chaining
      Throws:
      IllegalArgumentException - if name is null

    • body

      public ApiRequest body(Object body)
      Sets the request body. Can be a String, Map, or any object that will be JSON serialized.
      Parameters:
      body - the request body
      Returns:
      this request for chaining
      Throws:
      IllegalArgumentException - if body is null

    • multipart

      public MultipartRequest multipart()
      Converts this request to a multipart request for file uploads.
      Returns:
      multipart request builder

    • download

      public File download(File file)
      Downloads the response to a file.
      Parameters:
      file - the target file
      Returns:
      the downloaded file
      Throws:
      ApiException - if download fails

    • download

      public File download(Path path)
      Downloads the response to a file path.
      Parameters:
      path - the target file path
      Returns:
      the downloaded file
      Throws:
      ApiException - if download fails

    • download

      public File download(String filename)
      Downloads the response to a file with the specified filename.
      Parameters:
      filename - the target filename
      Returns:
      the downloaded file
      Throws:
      ApiException - if download fails

    • downloadStream

      public ManagedInputStream downloadStream()
      Downloads the response as a ManagedInputStream for streaming. The returned stream implements AutoCloseable and should be used in try-with-resources.

      Usage example:

       try (ManagedInputStream stream = request.downloadStream()) {
     byte[] data = stream.readAllBytes();
 } // Stream is automatically closed
      Returns:
      managed input stream for reading the response
      Throws:
      ApiException - if download fails

    • execute

      public ApiResponse execute()
      Executes the request synchronously and returns the response.
      Returns:
      ApiResponse containing the result
      Throws:
      ApiException - if the request fails

    • executeAsync

      public CompletableFuture<ApiResponse> executeAsync()
      Executes the request asynchronously and returns a CompletableFuture.
      Returns:
      CompletableFuture containing the response

    • async

      public void async(Consumer<ApiResponse> callback)
      Executes the request asynchronously with a callback.
      Parameters:
      callback - function to handle the response

    • getUrl

      public String getUrl()

    • getMethod

      public String getMethod()

    • getHeaders

      public Map<String,String> getHeaders()

    • getQueryParams

      public Map<String,Object> getQueryParams()

    • getBody

      public Object getBody()

    • isMultipart

      public boolean isMultipart()