FS.AspNetCore.ResponseWrapper

Enterprise-grade API response wrapper for ASP.NET Core - standardize your APIs with zero code changes.

Transform your raw controller responses into rich, metadata-enhanced API responses automatically. Add comprehensive error handling, request tracking, pagination support, and enterprise features without modifying existing code.

🎯 Why Use This?

Problem: Your API returns inconsistent response formats, lacks proper error handling, and provides no request tracking or metadata.

Solution: Add one NuGet package and 2 lines of code - get enterprise-grade API responses automatically.

// Before
public async Task<User> GetUser(int id) => await _userService.GetUserAsync(id);

// After (no code changes needed!)
public async Task<User> GetUser(int id) => await _userService.GetUserAsync(id);

Automatic transformation:

{
  "success": true,
  "data": { "id": 1, "name": "John Doe" },
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T10:30:45.123Z",
    "executionTimeMs": 42,
    "path": "/api/users/1",
    "method": "GET"
  }
}

✨ Key Features

• ✅ Zero Code Changes - Works with existing controllers automatically
• 🔄 Automatic Response Wrapping - Consistent format for all endpoints
• 🚨 Global Error Handling - 12 built-in exception types with error codes
• ⏱️ Performance Monitoring - Automatic execution time tracking
• 📄 Universal Pagination - Works with ANY pagination library (duck typing)
• 🏷️ Smart Metadata Extraction - StatusCode, Message, and custom metadata
• 🔍 Request Tracing - Correlation IDs for distributed systems
• 🎛️ Highly Configurable - Control every aspect of wrapping behavior
• 🛡️ Production-Ready - .NET 10.0 support, minimal overhead

📦 Quick Start

1. Install Package

dotnet add package FS.AspNetCore.ResponseWrapper

2. Configure (2 lines of code)

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddResponseWrapper(); // 👈 Line 1

var app = builder.Build();

app.UseMiddleware<GlobalExceptionHandlingMiddleware>(); // 👈 Line 2 (optional but recommended)
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

3. That's It! 🎉

Your existing controllers now return wrapped responses automatically:

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<User> GetUser(int id)
    {
        var user = await _userService.GetUserAsync(id);
        if (user == null)
            throw new NotFoundException("User", id);
        return user;
    }
}

Success Response:

{
  "success": true,
  "data": { "id": 1, "name": "John Doe", "email": "john@example.com" },
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T10:30:45.123Z",
    "executionTimeMs": 42
  }
}

Error Response:

{
  "success": false,
  "data": null,
  "message": "The requested item could not be found",
  "statusCode": "NOT_FOUND",
  "errors": ["User (123) was not found."],
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T10:32:15.456Z"
  }
}

📚 Documentation

Core Package

• 📖 Getting Started Guide - Step-by-step setup and basic usage
• 🔧 Core Features - Response structure, interfaces, error handling
• 📄 Pagination Support - Universal pagination with any library
• ⚙️ Configuration Guide - All configuration options explained
• 💡 Examples - Real-world usage examples
• 🐛 Troubleshooting - Common issues and solutions

Enterprise Extensions

• 🚀 Enterprise Features Overview - All enterprise packages
• 📊 OpenAPI Integration - Swagger, NSwag, Scalar support
• 📈 OpenTelemetry & Tracing - Distributed tracing and metrics
• ⚡ Caching & Performance - Memory, Redis, SQL Server caching
• 🔒 Data Transformation - Masking, field selection, GDPR
• 🎨 Preset Configurations - Quick setup for common scenarios

🎯 Common Use Cases

Basic API with Error Handling

builder.Services.AddResponseWrapper();
app.UseMiddleware<GlobalExceptionHandlingMiddleware>();

API with Pagination

// Works automatically with ANY pagination library!
[HttpGet]
public async Task<PagedResult<Product>> GetProducts(int page = 1)
    => await _service.GetPagedAsync(page, 20);

API with Custom Status Codes

public class LoginResult : IHasStatusCode, IHasMessage
{
    public string Token { get; set; }
    public string StatusCode { get; set; } = "LOGIN_SUCCESS";
    public string Message { get; set; } = "Welcome back!";
}

Enterprise API with All Features

// Install meta package
dotnet add package FS.AspNetCore.ResponseWrapper.Extensions

// One-line setup
builder.Services.AddResponseWrapperWithPreset(PresetType.Enterprise, "MyAPI");
app.UseResponseWrapperExtensions();

🏢 Enterprise Features

Install the all-in-one enterprise package:

dotnet add package FS.AspNetCore.ResponseWrapper.Extensions

Includes:

• 📊 OpenAPI Integration - Swashbuckle, NSwag, Scalar with enhanced schemas
• 📈 OpenTelemetry - W3C trace context, distributed tracing, custom metrics
• ⚡ Caching - Memory, Redis, SQL Server with ETag support
• 🔒 Transformation - Data masking (PII protection), field selection, GDPR compliance
• 🎨 Presets - 9 pre-configured setups (Minimal, Basic, Standard, Advanced, Enterprise, GDPR, Performance, Development, Production)

Quick Enterprise Setup:

// One line gets you everything
builder.Services.AddResponseWrapperWithPreset(PresetType.Enterprise, "MyAPI");
app.UseResponseWrapperExtensions();

See Enterprise Features Documentation for details.

🎛️ Configuration Example

builder.Services.AddResponseWrapper(options =>
{
    // Enable/disable features
    options.EnableExecutionTimeTracking = true;
    options.EnablePaginationMetadata = true;
    options.EnableCorrelationId = true;

    // Exclude specific endpoints
    options.ExcludedPaths = new[] { "/health", "/metrics" };

    // Customize error messages
}, errorMessages =>
{
    errorMessages.ValidationErrorMessage = "Please check your input";
    errorMessages.NotFoundErrorMessage = "Item not found";
});

🚨 Built-in Exception Types

12 exception types with automatic error code extraction:

• ValidationException - Input validation errors (400)
• NotFoundException - Resource not found (404)
• BusinessException - Business rule violations (400)
• ConflictException - Resource conflicts (409)
• UnauthorizedException - Authentication required (401)
• ForbiddenAccessException - Authorization failed (403)
• BadRequestException - Invalid requests (400)
• TimeoutException - Operation timeout (408)
• TooManyRequestsException - Rate limiting (429)
• ServiceUnavailableException - Service down (503)
• CustomHttpStatusException - Any custom status code
• ApplicationExceptionBase - Base for custom exceptions

All exceptions include automatic error codes for client-side handling.

📊 Response Structure

{
  "success": true,           // Operation outcome
  "data": { ... },           // Your business data
  "message": "...",          // Optional message
  "statusCode": "...",       // Application status code
  "errors": [...],           // Error messages (if any)
  "metadata": {              // Request metadata
    "requestId": "...",      // Unique request ID
    "timestamp": "...",      // Response timestamp
    "executionTimeMs": 42,   // Execution time
    "correlationId": "...",  // Distributed tracing
    "path": "/api/users",    // Request path
    "method": "GET",         // HTTP method
    "pagination": { ... },   // Pagination info (if applicable)
    "additional": { ... }    // Custom metadata
  }
}

🔧 Requirements

• .NET 10.0 or later
• ASP.NET Core Web API project

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📞 Support & Links

• Documentation: GitHub Repository
• NuGet Package: FS.AspNetCore.ResponseWrapper
• Issues: Report bugs or request features
• Enterprise Package: FS.AspNetCore.ResponseWrapper.Extensions

🌟 What's Next?

1. ✅ Install the package
2. 📖 Read the Getting Started Guide
3. 💡 Check out Examples
4. 🚀 Explore Enterprise Features

---

Made with ❤️ by Furkan Sarıkaya

Transform your ASP.NET Core APIs with enterprise-grade response wrapping. Install today and elevate your API development!