QERP.Response 1.5.2

Qerp.QERP.Response

Standardized API response package for ASP.NET Core with built-in global exception handler middleware and message management. Provides consistent response models, typed exceptions, W3C TraceId/SpanId correlation, application-level response codes, EF Core message lookup, optional Redis caching, and CRUD operations for response messages.

Features

• Fluent builder pattern -- configure with AddStructuredResponse(api => api.UsePostgreSql(...).UseRedis(...).UseMessageManagement(...))
• Simple response model -- ApiResponse<T> generic wrapper for any data type with a Status flag.
• Global exception handler -- middleware catches all unhandled exceptions and returns standardized error responses
• Built-in exception types -- NotFoundException, BadRequestException, ValidationException, UnauthorizedException, ForbiddenException, ConflictException, and ServiceUnavailableException
• Message management -- opt-in CRUD service for response messages (Seed, Add, Edit, Activate, Deactivate, List)
• W3C Trace Context -- automatic TraceId and SpanId from OpenTelemetry activities
• Application response codes -- categorized enum (MessageCode) with ranges for Success, Client Errors, Auth Errors, and Server Errors
• Database-driven messages -- response messages stored in PostgreSQL via EF Core
• Optional Redis caching -- cache-aside pattern with automatic invalidation on mutations
• Read/write DB separation -- read connection for queries, write connection for management
• Auto-seed -- database is automatically seeded with default messages when message management is enabled
• Audit trail -- all entities inherit AuditEntity with CreatedBy, CreatedAt, UpdatedBy, UpdatedAt
• Multi-target -- supports net8.0, net9.0, and net10.0

Installation

dotnet add package QERP.Response

Quick Start

1. Register Services and Middleware

using QERP.Response.Extensions;

// Minimal (read-only DB, no Redis, no management)
builder.Services.AddStructuredResponse(api => api
    .UsePostgreSql("Host=localhost;Database=qerp;Username=postgres;Password=secret")
);

// Full (management + auto-seed + Redis)
builder.Services.AddStructuredResponse(api => api
    .UsePostgreSql("Host=read-replica;Database=qerp;...")
    .UseRedis("localhost:6379")
    .UseMessageManagement("Host=primary;Database=qerp;...")
);

var app = builder.Build();

app.UseStructuredResponse();  // registers exception handler and request logging

2. Use the Response Factory

using QERP.Response.Builders;
using QERP.Response.Enums;
using QERP.Response.Exceptions;

// --- Example 1: Success with default code (0 - Success) ---
app.MapGet("/api/products/{id}", async (int id, ResponseFactory response) =>
{
    var product = await productService.GetByIdAsync(id);
    if (product is null) throw new NotFoundException();

    var result = await response.SuccessAsync(product);
    return Results.Ok(result);
});

// --- Example 2: Success with custom code (1 - Created) ---
app.MapPost("/api/products", async (Product product, ResponseFactory response) =>
{
    await productService.AddAsync(product);
    var result = await response.SuccessAsync(product, MessageCode.Created);
    return Results.Json(result, statusCode: 201);
});

// --- Example 3: Manual failure with custom errors ---
app.MapPost("/api/validate", async (ValidateRequest req, ResponseFactory response) =>
{
    if (string.IsNullOrEmpty(req.Name))
    {
        var errors = new List<string> { "Name is required for validation." };
        var result = await response.FailAsync<object>(MessageCode.ValidationError, errors);
        return Results.BadRequest(result);
    }

    return Results.Ok(await response.SuccessAsync(new { Valid = true }));
});

3. Response Output

Success:

{
  "status": true,
  "code": 0,
  "traceId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "spanId": "1a2b3c4d5e6f7a8b",
  "timestamp": "2026-03-03T14:10:00Z",
  "message": "Operation completed successfully.",
  "data": {
    "id": 1,
    "name": "Laptop",
    "price": 1299.99
  }
}

Exception (handled by middleware):

{
  "status": false,
  "code": 102,
  "traceId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "spanId": "1a2b3c4d5e6f7a8b",
  "timestamp": "2026-03-03T14:10:05Z",
  "message": "The requested resource was not found.",
  "errors": ["Product 123 was not found."],
  "data": null
}

Builder Configuration

Factory Methods

Inject ResponseFactory to create responses manually:

await response.SuccessAsync(data);
await response.SuccessAsync(data, MessageCode.Created);
await response.FailAsync<Product>(MessageCode.NotFound);
await response.FailAsync<Product>(MessageCode.NotFound, errors);

Message Management Service

Available when .UseMessageManagement(writeConn) is configured. Inject IApplicationMessageManagementService:

using QERP.Response.Services;
using QERP.Response.Models;

app.MapGet("/api/messages", async (IApplicationMessageManagementService mgmt) =>
{
    var messages = await mgmt.ListAsync();
    return Results.Ok(messages);
});

app.MapPost("/api/messages", async (MessageRequest req, IApplicationMessageManagementService mgmt) =>
{
    var created = await mgmt.AddAsync(req);
    return Results.Created($"/api/messages/{created.Id}", created);
});

Built-in Exception Types

Throw these anywhere in your code -- the middleware catches them and returns the correct HTTP status with a standardized ApiResponse model:

Custom Exceptions

You can throw BaseException directly for custom HTTP status codes:

throw new BaseException("Rate limit exceeded", HttpStatusCode.TooManyRequests);

Message Codes (MessageCode)

Detailed Demo

For a full demo application, see the tests/response-pkg.app project. It includes:

1. Program.cs: Full configuration with PostgreSQL, Redis, and Logging.
2. ProductsController: Real-world CRUD examples using ResponseFactory.
3. TestController: Demonstration of all built-in exception types.
4. MessagesController: CRUD operations for managing response messages in the database.

Running the Demo

1. Configure the connection strings in appsettings.json.
2. Run the project: dotnet run --project tests/response-pkg.app.
3. Use the response-pkg.app.http file to test endpoints.

License

This project is licensed under the MIT License. See the LICENSE file for details.