Request Builder

RequestBuilder provides a fluent, chainable API for constructing HTTP requests. Every method returns this (except build()), so calls can be chained in any order before the final .build() call.

Basic Construction

import { RequestBuilder, HttpMethod } from '@yildizpay/http-adapter';

const request = new RequestBuilder('https://api.example.com')
  .setEndpoint('/users')
  .setMethod(HttpMethod.POST)
  .addHeader('Authorization', 'Bearer token')
  .setBody({ name: 'Alice', email: '[email protected]' })
  .build();

The base URL is passed to the constructor. All other properties are set via builder methods.

API Reference

setEndpoint(path: string)

Appends a path segment to the base URL. Leading slashes are handled automatically.

new RequestBuilder('https://api.example.com')
  .setEndpoint('/users/123')
// → resolves to https://api.example.com/users/123

setMethod(method: HttpMethod)

Sets the HTTP verb. Defaults to HttpMethod.GET if not called.

enum HttpMethod {
  GET     = 'GET',
  POST    = 'POST',
  PUT     = 'PUT',
  PATCH   = 'PATCH',
  DELETE  = 'DELETE',
  HEAD    = 'HEAD',
  OPTIONS = 'OPTIONS',
}

addHeader(name: string, value: string)

Adds a single request header. Can be called multiple times.

builder
  .addHeader('Authorization', 'Bearer my-token')
  .addHeader('X-Request-Source', 'payment-service')

setBody(body: unknown)

Sets the request body. The value is automatically JSON-serialized and Content-Type: application/json is added.

setQueryParams(params: Record<string, string | number | boolean>)

Appends query parameters to the URL.

new RequestBuilder('https://api.example.com')
  .setEndpoint('/orders')
  .setQueryParams({ page: 2, limit: 50, status: 'pending' })
// → https://api.example.com/orders?page=2&limit=50&status=pending

validateWith(...validators: ResponseValidator[])

Attaches one or more response validators that run automatically after the HTTP call succeeds. See Response Validators for details.

builder.validateWith(new PaymentSchemaValidator(), new PaymentStatusValidator())

Type Safety

The response type T is supplied at the send() call, not on the builder. The built Request object is type-agnostic and reusable:

interface Product {
  id: string;
  name: string;
  price: number;
}

const request = new RequestBuilder('https://api.example.com')
  .setEndpoint('/products/abc')
  .build();

const response = await adapter.send<Product>(request);
// response.data is typed as Product

Reusing Requests

build() produces an immutable Request object. It is safe to define request templates once and send them multiple times — each call gets its own correlationId automatically:

const getUser = new RequestBuilder('https://api.example.com')
  .setEndpoint('/users/me')
  .setMethod(HttpMethod.GET)
  .build();

// Safe to reuse — no shared mutable state
const r1 = await adapter.send<User>(getUser);
const r2 = await adapter.send<User>(getUser);

Per-Request Configuration Overrides

Individual requests can override the adapter's global retry policy, circuit breaker, and interceptors without affecting other requests. See Request-Level Overrides.