TAF.MetaData.SDK 4.1.0

TAF Metadata Client SDK

A professional, HTTP-based SDK for consuming TAF Metadata Service APIs. This SDK follows Clean Architecture and SOLID principles, providing enterprise-grade metadata retrieval capabilities with automatic context resolution.

🏗️ Architecture & Design Principles

✅ Clean Architecture - Proper separation of layers: Client, Infrastructure, Services, Interfaces, Core
✅ SOLID Principles - Single responsibility, dependency inversion, interface segregation
✅ Industry Standards - Follows AWS, Azure, Stripe SDK naming conventions
✅ HTTP-First - Lightweight, direct API communication
✅ Auto Context Resolution - Automatic TenantId/AppId extraction from headers
✅ Comprehensive Error Handling - Proper exception mapping and status codes
✅ Dependency Injection - Seamless .NET DI integration with validation

📦 Installation

dotnet add package TAF.MetaData.SDK

🚀 Quick Start

1. Configuration

Add metadata service configuration to your appsettings.json:

{
  "MetadataService": {
    "BaseUrl": "https://your-metadata-service.com",
    "Timeout": 30
  }
}

2. Service Registration

Simple configuration from appsettings:

using TAF.MetaData.SDK.Extensions;

var builder = WebApplication.CreateBuilder(args);

// One-line registration with appsettings
builder.Services.AddMetadataClient(builder.Configuration);

var app = builder.Build();

Advanced manual configuration:

// Custom configuration
builder.Services.AddMetadataClient(options =>
{
    options.BaseUrl = "https://metadata-api.production.com";
    options.TimeoutSeconds = 45;
});

3. Usage

Inject and use the client in your services:

public class MyService
{
    private readonly IMetadataClient _metadataClient;
    
    public MyService(IMetadataClient metadataClient)
    {
        _metadataClient = metadataClient;
    }
    
    public async Task<AppObjectResponse?> GetUserProfile()
    {
        // Context (TenantId, AppId) automatically resolved from HTTP headers
        return await _metadataClient.GetAppObjectAsync(
            appObjectName: "UserProfile", 
            version: "1.2.0" // optional
        );
    }
}

4. HTTP Headers (Required)

Ensure your HTTP requests include the required context headers:

GET /api/myendpoint
TenantId: 123e4567-e89b-12d3-a456-426614174000
AppId: 987fcdeb-51a2-43d1-9f12-345678901234
CorrelationId: req-12345-67890 (optional)

📚 API Reference

IMetadataClient

GetAppObjectAsync

Task<AppObjectResponse?> GetAppObjectAsync(
    string appObjectName,
    string? version = null,
    CancellationToken cancellationToken = default)

Parameters:

• appObjectName - Name of the application object to retrieve
• version - Optional version filter (default: null)
• cancellationToken - Cancellation token

Returns: AppObjectResponse if found, null if not found

Throws:

• ArgumentException - When appObjectName is null/empty
• InvalidOperationException - When required headers are missing
• MetadataServiceException - When service operation fails

📋 Response Models

AppObjectResponse

public class AppObjectResponse
{
    public Guid Id { get; set; }
    public Guid TenantId { get; set; }
    public Guid AppId { get; set; }
    public Guid AppObjectId { get; set; }
    public string AppObjectName { get; set; }
    public string AppObjectJson { get; set; }
    public string? Version { get; set; }
    public bool IsCustom { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
}

🏛️ Clean Architecture Structure

TAF.Metadata.SDK/
├── Client/              # Consumer-facing implementations
│   └── HttpMetadataClient.cs
├── Infrastructure/      # External dependencies (HTTP context)
│   └── HttpContextProvider.cs
├── Services/           # Internal business services
│   ├── MetadataUrlBuilder.cs
│   ├── MetadataHttpRequestFactory.cs
│   └── MetadataResponseProcessor.cs
├── Interfaces/         # Contracts/abstractions
│   ├── IMetadataClient.cs
│   ├── IContextProvider.cs
│   └── ...
├── Core/              # Domain objects
│   └── MetadataContext.cs
├── Configuration/     # Options pattern
│   └── MetadataServiceOptions.cs
└── Extensions/        # DI registration
    └── ServiceCollectionExtensions.cs

🎯 SOLID Principles Implementation

Single Responsibility Principle (SRP)

• HttpMetadataClient - Orchestrates the request flow
• MetadataUrlBuilder - Builds URLs only
• MetadataHttpRequestFactory - Creates HTTP requests only
• MetadataResponseProcessor - Processes responses only
• HttpContextProvider - Resolves context from headers only

Open/Closed Principle (OCP)

• SDK is extensible via interfaces
• New response processors or context providers can be added

Dependency Inversion Principle (DIP)

• All dependencies via abstractions (IMetadataClient, IContextProvider)
• Easy to mock and test

Interface Segregation Principle (ISP)

• Small, focused interfaces
• Each interface has a single responsibility

⚡ Auto Context Resolution

The SDK automatically extracts context from HTTP request headers:

// No manual context needed - extracted automatically!
var appObject = await _metadataClient.GetAppObjectAsync("UserProfile");

// Behind the scenes:
// 1. HttpContextProvider reads Request.Headers["TenantId"]
// 2. HttpContextProvider reads Request.Headers["AppId"] 
// 3. HttpContextProvider reads Request.Headers["CorrelationId"] (optional)
// 4. Context passed to metadata service automatically

🛡️ Error Handling

try
{
    var userProfile = await _metadataClient.GetAppObjectAsync("UserProfile");
    if (userProfile == null)
    {
        // Object not found (404)
        Console.WriteLine("UserProfile not found");
    }
}
catch (InvalidOperationException ex)
{
    // Missing required headers
    Console.WriteLine($"Missing context: {ex.Message}");
}
catch (MetadataServiceException ex)
{
    // Service errors (network, timeout, API errors)
    Console.WriteLine($"Service error: {ex.Message}, Status: {ex.StatusCode}");
}

🔧 Configuration Options

MetadataServiceOptions

public class MetadataServiceOptions
{
    public string BaseUrl { get; set; } = string.Empty;
    public int TimeoutSeconds { get; set; } = 30;
}

Configuration validation:

• BaseUrl - Required, must be valid URL
• TimeoutSeconds - Must be between 1 and 300 seconds

🌟 Key Features

• 🔄 Industry Standard Naming - IMetadataClient follows AWS/Azure patterns
• ⚡ One-Line Setup - AddMetadataClient(configuration)
• 🤖 Auto Context - No manual TenantId/AppId passing
• 🛡️ Secure - Fixed SSL certificate validation
• 📊 Lightweight - HTTP-only, no message bus dependencies
• 🧪 Testable - All dependencies mockable via interfaces
• ⚙️ Configurable - Supports both appsettings and manual config

📦 Dependencies

• .NET 8.0+ - Modern .NET runtime
• Microsoft.AspNetCore.Http - HTTP context access
• Microsoft.Extensions.DependencyInjection - DI container
• Microsoft.Extensions.Http - HTTP client factory
• System.ComponentModel.Annotations - Configuration validation

🤝 Contributing

This SDK is maintained by the TAF Development Team. For issues or feature requests, please contact the development team.

📄 License

MIT License - see LICENSE file for details.

🤖 Generated with Claude Code