# TeaQL Tool API: HTTP Client (Java)

Use `ctx.http()` to make outgoing HTTP requests. This client is fully integrated with the TeaQL runtime and automatically logs request/response details if tracing is enabled.

> [!WARNING]
> Always provide a `.purpose()` describing the business reason for the request.

## Required Dependencies

Add the `teaql-tool` dependency with HTTP support to your `pom.xml`:

```xml
<dependency>
    <groupId>io.teaql</groupId>
    <artifactId>teaql-tool</artifactId>
    <version>${teaql.version}</version>
</dependency>
```

## GET Request

```java
var response = ctx.http()
    .purpose("fetch user profile from external identity provider")
    .get("https://api.example.com/users/123")
    .header("Authorization", "Bearer token")
    .execute();

if (response.isSuccess()) {
    JsonNode json = response.json();
}
```

## POST Request with JSON

```java
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectNode payload = new ObjectMapper().createObjectNode()
    .put("event", "user_signed_up")
    .put("userId", 123);

var response = ctx.http()
    .purpose("notify external webhook of user signup")
    .post("https://webhook.example.com/notify")
    .json(payload)
    .execute();
```

## Key Methods
- `.purpose(reason)`: **(Required)** Describe why this request is being made.
- `.get(url)` / `.post(url)` / `.put(url)` / `.delete(url)`: Start a request.
- `.header(key, value)`: Add an HTTP header.
- `.json(payload)`: Set the body as JSON.
- `.form(params)`: Set the body as URL-encoded form.
- `.timeout(Duration)`: Set a custom timeout.
- `.execute()`: Execute the request.