AstreCode.Backend.Shared.Integration 8.0.0

AstreCode.Backend.Shared.Integration

External service integration framework for AstreCode microservices.

Description

The AstreCode.Backend.Shared.Integration package provides essential integration components for building robust and scalable .NET 8.0 backend services. This package includes HTTP client management, external service integration, and resilience patterns for reliable service communication.

Installation

To install this package, use the .NET CLI:

dotnet add package AstreCode.Backend.Shared.Integration

Or via Package Manager Console:

Install-Package AstreCode.Backend.Shared.Integration

Features

🌐 HTTP Client Management

• JsonHandler: JSON-based HTTP client with comprehensive error handling
• XmlHandler: XML-based HTTP client for legacy system integration
• Authentication Support: Multiple authentication schemes (Bearer, Basic, API Key)
• Certificate Support: Client certificate authentication

🛡️ Resilience Patterns

• Retry Policy: Configurable retry mechanisms with exponential backoff
• Circuit Breaker: Automatic circuit breaking for failing services
• Timeout Policy: Request timeout management
• Bulkhead Isolation: Resource isolation and concurrency limiting
• Fallback Policy: Graceful degradation with fallback responses

🔐 Authentication Integration

• Bearer Token: JWT and OAuth token support
• Basic Authentication: Username/password authentication
• API Key: API key-based authentication
• Client Certificates: X.509 certificate authentication

📊 Request/Response Handling

• JSON Serialization: Automatic JSON serialization/deserialization
• XML Serialization: XML request/response handling
• Query Parameter Building: Dynamic query parameter construction
• Header Management: Request header configuration

🔧 Configuration Extensions

• Integration Configuration: Service registration helpers
• Policy Configuration: Resilience policy setup
• HttpClient Configuration: HTTP client factory setup

Example Usage

JSON Handler

using Shared.Integration.Handlers;

public class ExternalApiService
{
    private readonly IJsonHandler _jsonHandler;

    public ExternalApiService(IJsonHandler jsonHandler)
    {
        _jsonHandler = jsonHandler;
    }

    public async Task<UserDto> GetUserAsync(int userId)
    {
        var queryParams = new { id = userId };
        var headers = new Dictionary<string, string>
        {
            ["Accept"] = "application/json"
        };
        var authInfo = new AuthenticationInfo
        {
            Scheme = "Bearer",
            Token = "your-jwt-token"
        };

        return await _jsonHandler.GetDataAsync<UserDto>(
            "https://api.example.com/users",
            headers,
            queryParams,
            authInfo
        );
    }

    public async Task<UserDto> CreateUserAsync(CreateUserDto user)
    {
        var authInfo = new AuthenticationInfo
        {
            Scheme = "Bearer",
            Token = "your-jwt-token"
        };

        return await _jsonHandler.PostDataAsync<UserDto>(
            "https://api.example.com/users",
            null,
            null,
            user,
            authInfo
        );
    }
}

XML Handler

using Shared.Integration.Handlers;

public class LegacySystemService
{
    private readonly IXmlHandler _xmlHandler;

    public LegacySystemService(IXmlHandler xmlHandler)
    {
        _xmlHandler = xmlHandler;
    }

    public async Task<OrderDto> GetOrderAsync(string orderId)
    {
        var queryParams = new { orderId = orderId };
        var authInfo = new AuthenticationInfo
        {
            Scheme = "Basic",
            Username = "username",
            Password = "password"
        };

        return await _xmlHandler.GetDataAsync<OrderDto>(
            "https://legacy.example.com/orders",
            null,
            queryParams,
            authInfo
        );
    }
}

Certificate Authentication

public class SecureApiService
{
    private readonly IJsonHandler _jsonHandler;

    public async Task<SecureDataDto> GetSecureDataAsync()
    {
        var authInfo = new AuthenticationInfo
        {
            Scheme = "Certificate",
            CertificatePath = "path/to/certificate.pfx",
            CertificatePassword = "certificate-password"
        };

        return await _jsonHandler.GetDataAsync<SecureDataDto>(
            "https://secure-api.example.com/data",
            null,
            null,
            authInfo,
            includeCertificate: true,
            certficatePath: "path/to/certificate.pfx"
        );
    }
}

Integration Configuration

using Shared.Integration;

// In Program.cs
builder.Services.IntegrationConfiguration(builder.Configuration);

Custom Authentication

public class CustomAuthService
{
    private readonly IJsonHandler _jsonHandler;

    public async Task<ApiResponse> CallApiWithCustomAuthAsync()
    {
        var headers = new Dictionary<string, string>
        {
            ["X-API-Key"] = "your-api-key",
            ["X-Custom-Header"] = "custom-value"
        };

        var authInfo = new AuthenticationInfo
        {
            Scheme = "Custom"
        };

        return await _jsonHandler.GetDataAsync<ApiResponse>(
            "https://api.example.com/data",
            headers,
            null,
            authInfo
        );
    }
}

Configuration

Service Registration

// In Program.cs
builder.Services.IntegrationConfiguration(builder.Configuration);

Resilience Policy Configuration

The integration framework automatically configures the following resilience policies:

• Retry Policy: 3 retries with exponential backoff
• Circuit Breaker: Opens after 5 failures, stays open for 30 seconds
• Timeout Policy: 10-second timeout per request
• Bulkhead Policy: Maximum 5 concurrent calls with queue of 10
• Fallback Policy: Returns ServiceUnavailable response on complete failure

Custom Policy Configuration

// You can customize policies by modifying the IntegrationConfigurationExtensions
public static void IntegrationConfiguration(this IServiceCollection services, IConfiguration configuration)
{
    services.AddHttpClient<JsonHandler>()
        .AddPolicyHandler(HttpPolicyExtensions
            .HandleTransientHttpError()
            .RetryAsync(5)) // Custom retry count
        .AddPolicyHandler(HttpPolicyExtensions
            .HandleTransientHttpError()
            .CircuitBreakerAsync(3, TimeSpan.FromSeconds(60))); // Custom circuit breaker
}

Authentication Schemes

Bearer Token

var authInfo = new AuthenticationInfo
{
    Scheme = "Bearer",
    Token = "your-jwt-token"
};

Basic Authentication

var authInfo = new AuthenticationInfo
{
    Scheme = "Basic",
    Username = "username",
    Password = "password"
};

API Key

var authInfo = new AuthenticationInfo
{
    Scheme = "ApiKey",
    ApiKey = "your-api-key"
};

Client Certificate

var authInfo = new AuthenticationInfo
{
    Scheme = "Certificate",
    CertificatePath = "path/to/certificate.pfx",
    CertificatePassword = "password"
};

Dependencies

This package depends on the following NuGet packages:

• Microsoft.AspNetCore.WebUtilities (8.0.8) - Web utilities
• Microsoft.Extensions.Http (8.0.0) - HTTP client factory
• Microsoft.Extensions.Http.Polly (8.0.8) - Resilience policies

Requirements

• .NET 8.0 or later
• ASP.NET Core 8.0 or later

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Support

For support and questions, please contact the AstreCode development team.

Changelog

See CHANGELOG.md for version history and changes.

AstreCode.Backend.Shared.Integration - Version 8.0.0