Request Builder

RequestBuilder, HTTP istekleri oluşturmak için akıcı, zincirleme bir API sağlar. build() dışındaki her metot this döndürür; bu sayede çağrılar son .build() çağrısından önce herhangi bir sırayla zincirlenebilir.

Temel Kullanım

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();

Temel URL constructor'a geçirilir. Diğer tüm özellikler builder metotları aracılığıyla ayarlanır.

API Referansı

setEndpoint(path: string)

Temel URL'ye bir yol segmenti ekler. Baştaki eğik çizgiler otomatik olarak işlenir.

new RequestBuilder('https://api.example.com')
  .setEndpoint('/users/123')
// → https://api.example.com/users/123 olarak çözümlenir

setMethod(method: HttpMethod)

HTTP fiilini ayarlar. Çağrılmazsa varsayılan olarak HttpMethod.GET kullanılır.

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

addHeader(name: string, value: string)

Tek bir istek başlığı ekler. Birden fazla başlık eklemek için birden fazla kez çağrılabilir.

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

setBody(body: unknown)

İstek gövdesini ayarlar. Değer otomatik olarak JSON'a serileştirilir ve Content-Type: application/json başlığı eklenir.

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

URL'ye sorgu parametreleri ekler.

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[])

HTTP çağrısı başarılı olduktan sonra otomatik olarak çalışan bir veya daha fazla yanıt doğrulayıcı ekler. Ayrıntılar için Yanıt Doğrulayıcılar sayfasına bakın.

builder.validateWith(new OdemeSchemaValidator(), new OdemeDurumValidator())

Tip Güvenliği

Yanıt tipi T, builder'da değil send() çağrısında belirtilir. Oluşturulan Request nesnesi tip bağımsızdır ve yeniden kullanılabilir:

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

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

const response = await adapter.send<Urun>(request);
// response.data, Urun olarak tiplendirilmiştir

İstekleri Yeniden Kullanma

build(), değiştirilemez (immutable) bir Request nesnesi üretir. İstek şablonlarını bir kez tanımlayıp birden fazla kez güvenle gönderebilirsiniz — her çağrı otomatik olarak kendi correlationId'sini alır:

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

// Güvenle yeniden kullanılabilir — paylaşılan değişken durum yok
const r1 = await adapter.send<User>(getMeRequest);
const r2 = await adapter.send<User>(getMeRequest);

İstek Bazlı Yapılandırma Geçersiz Kılmaları

Bireysel istekler, diğer istekleri etkilemeden adaptörün global retry politikasını, circuit breaker'ını ve interceptor'larını geçersiz kılabilir. Ayrıntılar için İstek Bazlı Geçersiz Kılma sayfasına bakın.