Package: groovy.http

## [Groovy] Class HttpBuilder

- groovy.http.HttpBuilder

-     @Incubating
      final class HttpBuilder
      extends Object

  Tiny DSL over JDK HttpClient.

  Redirect following is opt-in; see Config.followRedirects for the policy applied to headers when a redirect leaves the origin of the first request.

  Since:
    6.0.0

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `static class` | `HttpBuilder.Config` | Configuration DSL used to create an HttpBuilder.
    `static class` | `HttpBuilder.RequestSpec` | Per-request configuration DSL used by the request methods.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `HttpResult` | `delete(Object uri, Closure<?> spec)` Executes a synchronous `DELETE` request.
    `` | `CompletableFuture<HttpResult>` | `deleteAsync(Object uri, Closure<?> spec)` Executes an asynchronous `DELETE` request.
    `` | `HttpResult` | `get(Object uri, Closure<?> spec)` Executes a synchronous `GET` request.
    `` | `CompletableFuture<HttpResult>` | `getAsync(Object uri, Closure<?> spec)` Executes an asynchronous `GET` request.
    `` | `CompletableFuture<HttpStreamResult>` | `getStreamAsync(Object uri, Closure<?> spec)` Executes an asynchronous streaming `GET` request.
    `` | `static HttpBuilder` | `http(Closure<?> spec)` Creates an `HttpBuilder` from the supplied configuration closure.
    `` | `static HttpBuilder` | `http(String baseUri)` Creates an `HttpBuilder` with only a base URI configured.
    `` | `HttpResult` | `patch(Object uri, Closure<?> spec)` Executes a synchronous `PATCH` request.
    `` | `CompletableFuture<HttpResult>` | `patchAsync(Object uri, Closure<?> spec)` Executes an asynchronous `PATCH` request.
    `` | `HttpResult` | `post(Object uri, Closure<?> spec)` Executes a synchronous `POST` request.
    `` | `CompletableFuture<HttpResult>` | `postAsync(Object uri, Closure<?> spec)` Executes an asynchronous `POST` request.
    `` | `CompletableFuture<HttpStreamResult>` | `postStreamAsync(Object uri, Closure<?> spec)` Executes an asynchronous streaming `POST` request.
    `` | `HttpResult` | `put(Object uri, Closure<?> spec)` Executes a synchronous `PUT` request.
    `` | `CompletableFuture<HttpResult>` | `putAsync(Object uri, Closure<?> spec)` Executes an asynchronous `PUT` request.
    `` | `HttpResult` | `request(String method, Object uri, Closure<?> spec)` Executes a synchronous request with the supplied HTTP method.
    `` | `CompletableFuture<HttpResult>` | `requestAsync(String method, Object uri, Closure<?> spec)` Executes an asynchronous request with the supplied HTTP method.
    `` | `CompletableFuture<HttpStreamResult>` | `streamAsync(String method, Object uri, Closure<?> spec)` Streams the response body without buffering.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### HttpResult delete(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes a synchronous `DELETE` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        the buffered response wrapper

    - #### CompletableFuture<HttpResult> deleteAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous `DELETE` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the buffered response

    - #### HttpResult get(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes a synchronous `GET` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        the buffered response wrapper

    - #### CompletableFuture<HttpResult> getAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous `GET` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the buffered response

    - #### CompletableFuture<HttpStreamResult> getStreamAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous streaming `GET` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the streaming response wrapper

    - #### static HttpBuilder http(@DelegatesTo(value=Config, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Creates an `HttpBuilder` from the supplied configuration closure.

      Parameters:
        `spec` - configures the builder defaults
      Returns:
        a configured HTTP builder

    - #### static HttpBuilder http(String baseUri)

      Creates an `HttpBuilder` with only a base URI configured.

      Parameters:
        `baseUri` - the absolute base URI used to resolve relative requests
      Returns:
        a configured HTTP builder

    - #### HttpResult patch(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes a synchronous `PATCH` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        the buffered response wrapper

    - #### CompletableFuture<HttpResult> patchAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous `PATCH` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the buffered response

    - #### HttpResult post(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes a synchronous `POST` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        the buffered response wrapper

    - #### CompletableFuture<HttpResult> postAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous `POST` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the buffered response

    - #### CompletableFuture<HttpStreamResult> postStreamAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous streaming `POST` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the streaming response wrapper

    - #### HttpResult put(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes a synchronous `PUT` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        the buffered response wrapper

    - #### CompletableFuture<HttpResult> putAsync(Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous `PUT` request.

      Parameters:
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the buffered response

    - #### HttpResult request(String method, Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes a synchronous request with the supplied HTTP method.

      Parameters:
        `method` - the HTTP method to use
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        the buffered response wrapper

    - #### CompletableFuture<HttpResult> requestAsync(String method, Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Executes an asynchronous request with the supplied HTTP method.

      Parameters:
        `method` - the HTTP method to use
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the buffered response

    - #### CompletableFuture<HttpStreamResult> streamAsync(String method, Object uri, @DelegatesTo(value=RequestSpec, strategy=Closure.DELEGATE_FIRST)
      Closure<?> spec)

      Streams the response body without buffering. Returns an HttpStreamResult whose `bodyAsPublisher()` delivers `List<ByteBuffer>` chunks as they arrive — enabling `for await (chunk in result.bodyAsPublisher())` via the `FlowPublisherAdapter`.

      Streaming always uses `HttpResponse.BodyHandlers.ofPublisher()`; any `bodyHandler` configured on the `RequestSpec` is ignored.

      Streaming requests never follow redirects, whatever Config.followRedirects is set to: a 3xx response is returned as-is, and its `Location` header is left to the caller.

      Parameters:
        `method` - the HTTP method to use
        `uri` - the absolute or base-relative request URI
        `spec` - optionally customizes the request
      Returns:
        a future that completes with the streaming response wrapper