JEWEL-SDK 1.0.0

MapNests SDK

A .NET SDK for MapNests functionality with modern configuration patterns, validation, and dependency injection support.

Installation

Install the package via NuGet:

dotnet add package MapNests

Or via Package Manager Console:

Install-Package MapNests

Getting Started

Basic Usage

using MapNests.Public.Clients;

// Using builder pattern (recommended)
var client = new MapNestsClientBuilder()
    .WithApiKey("your-api-key")
    .WithOrigin("https://myapp.com")
    .Build();

// Health check
if (await client.Health.IsHealthyAsync())
{
    Console.WriteLine("API is healthy!");
}

// Demo operations
var demo = await client.Demo.CreateAsync(new CreateDemoRequest 
{ 
    Name = "Test", 
    Description = "Test description" 
});

var result = await client.Demo.GetAsync(demo.Id);
await client.Demo.UpdateAsync(demo.Id, new UpdateDemoRequest { Name = "Updated" });
await client.Demo.DeleteAsync(demo.Id);

Configuration Options

Builder Pattern

var client = new MapNestsClientBuilder()
    .WithApiKey("your-api-key")
    .WithOrigin("https://myapp.com")
    .WithTimeout(TimeSpan.FromSeconds(60))
    .WithRetryPolicy(policy =>
    {
        policy.MaxRetries = 3;
        policy.InitialDelay = TimeSpan.FromSeconds(1);
        policy.BackoffMultiplier = 2.0;
        policy.MaxDelay = TimeSpan.FromSeconds(30);
    })
    .WithCircuitBreaker(circuitBreaker =>
    {
        circuitBreaker.FailureThreshold = 5;
        circuitBreaker.DurationOfBreak = TimeSpan.FromSeconds(30);
        circuitBreaker.SamplingDuration = TimeSpan.FromMinutes(1);
    })
    .Build();

Environment Variables

using MapNests.Public.Configuration;

// Set environment variables:
// MAPNESTS_API_KEY=your-api-key
// MAPNESTS_ORIGIN=https://myapp.com
// MAPNESTS_TIMEOUT_SECONDS=60 (optional)

var client = EnvironmentConfiguration.CreateFromEnvironment();

Dependency Injection

using MapNests.Public;
using Microsoft.Extensions.DependencyInjection;

// Option 1: Direct configuration
services.AddMapNests(options =>
{
    options.ApiKey = "your-api-key";
    options.Origin = "https://myapp.com";
    options.Timeout = TimeSpan.FromSeconds(60);
});

// Option 2: From configuration (appsettings.json)
services.AddMapNests(configuration);

// Option 3: Using IHttpClientFactory (Recommended for Production)
services.AddMapNestsHttpClient(options =>
{
    options.ApiKey = "your-api-key";
    options.Origin = "https://myapp.com";
    options.RetryPolicy = new RetryPolicyOptions { MaxRetries = 3 };
    options.CircuitBreaker = new CircuitBreakerOptions { FailureThreshold = 5 };
});

// Option 4: IHttpClientFactory with IConfiguration
services.AddMapNestsHttpClient(configuration);

// Option 5: Using IOptions pattern
services.Configure<ApiClientOptions>(configuration.GetSection("MapNests"));
services.AddMapNestsWithOptions();

Configuration Binding (appsettings.json)

{
  "MapNests": {
    "ApiKey": "your-api-key",
    "Origin": "https://myapp.com",
    "Timeout": "00:01:00",
    "RetryPolicy": {
      "MaxRetries": 3,
      "InitialDelay": "00:00:01",
      "BackoffMultiplier": 2.0,
      "MaxDelay": "00:00:30"
    },
    "CircuitBreaker": {
      "FailureThreshold": 5,
      "DurationOfBreak": "00:00:30",
      "SamplingDuration": "00:01:00",
      "HalfOpenMaxAttempts": 1
    }
  }
}

// In Startup.cs or Program.cs
services.AddMapNests(configuration);

API Versioning

The SDK automatically uses the API version that matches the SDK version (e.g., SDK 1.0.0 → API v1). You can also access specific API versions:

// Use default version (matches SDK version)
var result = await client.Demo.GetAsync("id");

// Use specific version
var resultV1 = await client.Demo.V1.GetAsync("id");
var resultV2 = await client.Demo.V2.GetAsync("id");

Validation

The SDK uses data annotations for automatic validation:

• ApiKey and Origin are required ([Required])
• Timeout must be between 1 second and 5 minutes ([Range])
• RetryPolicyOptions properties have range validations

Validation occurs automatically when using DI extensions or can be called manually:

using MapNests.Public.Configuration;

var options = new ApiClientOptions
{
    ApiKey = "your-api-key",
    Origin = "https://myapp.com"
};

// Manual validation
ConfigurationValidation.Validate(options);

Requirements

This package targets both:

• .NET Standard 2.1 - For maximum compatibility
• .NET 8.0 - For modern .NET applications

Compatibility

The .NET Standard 2.1 target is compatible with:

• .NET Core 3.0+
• .NET Framework 4.8+
• .NET 5+
• .NET 6+
• .NET 7+
• .NET 8+

The .NET 8.0 target provides optimized performance for .NET 8+ applications.

Dependencies

• System.ComponentModel.Annotations (v5.0.0) - For validation attributes
• System.Text.Json (v10.0.2) - For JSON serialization
• Microsoft.Extensions.DependencyInjection.Abstractions (v10.0.2) - For DI support (optional)
• Microsoft.Extensions.Options (v10.0.2) - For configuration binding (optional)
• Microsoft.Extensions.Configuration.Binder (v10.0.2) - For configuration binding (optional)
• Microsoft.Extensions.Logging.Abstractions (v10.0.2) - For logging integration (optional)

Features

• ✅ Builder Pattern - Fluent API for configuration
• ✅ Options Pattern - Strongly-typed configuration
• ✅ Environment Variables - Configuration from environment
• ✅ Configuration Binding - Bind from appsettings.json
• ✅ Validation Attributes - Automatic validation with data annotations
• ✅ Retry Logic - Configurable exponential backoff
• ✅ Circuit Breaker - Prevents cascading failures with automatic recovery
• ✅ Dependency Injection - Full DI support with validation
• ✅ Structured Logging - Integration with Microsoft.Extensions.Logging
• ✅ Type Safety - Strongly typed APIs throughout
• ✅ API Versioning - Automatic version matching with SDK version, plus explicit version access

Documentation

For comprehensive documentation, see the docs directory:

Pattern Documentation

• Builder Pattern - Fluent API for configuration
• Options Pattern - Strongly-typed configuration with validation
• Retry Pattern - Automatic retry with exponential backoff
• Circuit Breaker - Prevents cascading failures
• Environment Variables - Configuration from environment
• Validation & Configuration Binding - Data annotations and appsettings.json binding
• Dependency Injection - DI integration guide
• Error Handling - Exception hierarchy and error handling

Architecture & Standards

• Architecture - SDK architecture overview
• SDK Standards - Industry standards reference
• Implementation Status - Current implementation status
• Versioning - Versioning strategy

For more information, visit the project repository.

License

This project is licensed under the MIT License.

Versioning

This project follows Semantic Versioning (SemVer).