NDB.Http 1.0.1

Lightweight and flexible HTTP integration layer for enterprise .NET applications. NDB.Http is designed as a transport layer module that supports:

• HTTP communication abstraction
• Per-request timeout control
• Per-request retry policy (Polly)
• Structured logging
• JSON-friendly API result model
• Optional mapping to NDB.Abstraction.Result

This module is suitable for:

• Microservice integration
• SAP / ERP integration
• External API consumption
• Internal service-to-service communication
• Orchestration platforms (CLAD-ready)

✨ Features

• HttpClient wrapper
• Per-request timeout configuration
• Per-request retry configuration
• Exponential backoff support
• ILogger integration
• Multipart/form-data support
• Token-based authentication (optional)
• Clean boundary with NDB.Abstraction

📦 Project Structure

NDB.Http
│
├── Abstractions
│   ├── IHttpClientHelper
│   ├── IAccessTokenProvider
│   └── IServiceApi
│
├── Models
│   ├── ApiResult<T>
│   ├── HttpResult<T>
│   ├── MultipartRequest
│   └── RequestOptions
│
├── Services
│   ├── HttpClientHelper
│   └── BaseApiService
│
├── Extensions
│   └── MappingExtension
│
└── Enums
└── RequestContentType

🚀 Installation

Register in DI:

services.AddHttpClient<IHttpClientHelper, HttpClientHelper>();

Optional token provider:

services.AddScoped<IAccessTokenProvider, MyTokenProvider>();

📘 HttpResult<T>

Represents the raw HTTP execution result.

public sealed class HttpResult<T>
{
    public bool Succeeded { get; }
    public T? Data { get; }
    public string? Raw { get; }
    public int StatusCode { get; }
    public string? ErrorMessage { get; }
}

This is transport-level result only.

📘 ApiResult<T>

JSON-friendly DTO for external API response.

public sealed class ApiResult<T>
{
    public int Code { get; set; }
    public bool Succeeded { get; set; }
    public string Message { get; set; }
    public string? Description { get; set; }
    public T? Data { get; set; }
}

Designed for deserialization.

⚙️ RequestOptions (Per Request Configuration)

public sealed class RequestOptions
{
    public TimeSpan? Timeout { get; init; }
    public int RetryCount { get; init; } = 0;
    public TimeSpan? RetryDelay { get; init; }
    public bool UseExponentialBackoff { get; init; } = true;
}

Example

var result = await _http.SendAsync<MyResponse>(
    HttpMethod.Get,
    "https://api.example.com/data",
    options: new RequestOptions
    {
        Timeout = TimeSpan.FromSeconds(60),
        RetryCount = 3
    });

🔁 Retry Behavior

Retry applies only when:

• Network exception
• Timeout (TaskCanceledException)
• HTTP 5xx response

HTTP 4xx responses are NOT retried.

⏱ Timeout Behavior

Timeout is handled per request using CancellationTokenSource. No global HttpClient timeout override is required.

🧱 BaseApiService

Convenience base class for building API services.

protected async Task<HttpResult<T>> GetAsync<T>(
    string path,
    RequestOptions? options = null);

Does NOT throw exception. Returns HttpResult<T>.

🔄 Mapping to Domain Result

If using NDB.Abstraction:

public static Result<T> ToDomainResult<T>(this ApiResult<T> api);
public static ListResult<T> ToListResult<T>(this ApiResult<List<T>> api);
public static Result<T> ToDomainResult<T>(this HttpResult<T> http);

Null-safe. No silent null propagation. No exception-based flow.

🧭 Design Philosophy

• Transport layer only
• No business logic
• Explicit result handling
• No silent failure
• No forced exception flow
• Flexible per request configuration
• Enterprise orchestration ready

🧠 Notes

• Do not mix business logic inside NDB.Http
• Handle mapping in application layer when possible
• Prefer explicit HttpResult handling over implicit unwrapping
• Retry and timeout should be configured per integration scenario