Usability Patterns That Reduce Support Tickets (and Make Your REST API Feel “Enterprise”)

 If you run an API long enough, you’ll notice the same support tickets repeating:

• “It failed, can you check logs?”
• “We’re getting 400 but don’t know what field is wrong.”
• “It worked yesterday, now it’s broken.”
• “We retried and created duplicates.”
• “We can’t reproduce it.”

These aren’t just “support problems” — they’re API usability problems. The fix is to design your API so it is self-explanatory, diagnosable, and safe to integrate.

Below are the highest-leverage usability patterns and a practical ASP.NET Core (Controllers) code sample you can drop into an enterprise API.

What “usability” means for an enterprise API

In enterprise systems, usability isn’t just UX — it’s integration UX. Your API is usable when:

• errors are consistent and actionable
• every request is traceable across services
• retry behavior is safe
• consumers can self-diagnose without emailing your team

The result: fewer support tickets and faster incident resolution.

The patterns (what you should implement)

Goal: make every request uniquely trackable across APIM → ingress → API → DB.

• Client can send: x-correlation-id: <string>
• If missing, the API generates one
• API echoes it back on every response
• API logs include it automatically

Benefit: when an exception happens, the client can paste the correlation ID into a ticket and you can find it in seconds.

2) Standard error format using Problem Details (RFC 7807)

Goal: every error looks the same to clients.

Your API should return:

• application/problem+json
• status, title, detail
• stable errorCode
• traceId and correlationId

Benefit: fewer “what does this mean?” tickets; easier client-side handling.

3) Global exception handling (don’t litter controllers with try/catch)

Goal: one place to:

• log exceptions once
• map exceptions to status codes
• return ProblemDetails consistently

Benefit: controllers stay clean; production errors become easy to search and triage.

4) Friendly validation errors (field-level)

Goal: return what field is wrong and why (no guesswork).

Benefit: eliminates back-and-forth with integrators.

A practical .NET implementation (Controllers)

This sample implements the two most ticket-killing patterns:

• Correlation ID everywhere
• Consistent ProblemDetails with traceId + correlationId + errorCode

Step 1 — Add a small middleware for x-correlation-id

using System.Diagnostics;

public sealed class CorrelationIdMiddleware : IMiddleware
{
  public const string HeaderName = "x-correlation-id";
  private readonly ILogger<CorrelationIdMiddleware> _logger;

  public CorrelationIdMiddleware(ILogger<CorrelationIdMiddleware> logger)
    => _logger = logger;

  public async Task InvokeAsync(HttpContext context, RequestDelegate next)
  {
    var incoming = context.Request.Headers.TryGetValue(HeaderName, out var v) ? v.ToString() : null;
    var correlationId = !string.IsNullOrWhiteSpace(incoming)
      ? incoming!
      : Guid.NewGuid().ToString("N");

    context.Items[HeaderName] = correlationId;

    // Ensure header is present even if downstream throws
    context.Response.OnStarting(() =>
    {
      context.Response.Headers[HeaderName] = correlationId;
      return Task.CompletedTask;
    });

    // Attach to distributed tracing (OpenTelemetry / App Insights)
    Activity.Current?.SetTag("correlationId", correlationId);

    // Attach to logs automatically
    using (_logger.BeginScope(new Dictionary<string, object>
    {
      ["correlationId"] = correlationId
    }))
    {
      await next(context);
    }
  }
}

Step 2 — Standardize errors using ProblemDetails

Create a tiny helper to build consistent error responses:

using System.Diagnostics;
using Microsoft.AspNetCore.Mvc;

public static class ApiProblems
{
  public static ProblemDetails Create(
    HttpContext http,
    int status,
    string title,
    string detail,
    string errorCode)
  {
    var traceId = Activity.Current?.TraceId.ToString() ?? http.TraceIdentifier;
    var correlationId = http.Items[CorrelationIdMiddleware.HeaderName]?.ToString();

    var pd = new ProblemDetails
    {
      Status = status,
      Title = title,
      Detail = detail,
      Type = $"https://httpstatuses.com/{status}"
    };

    pd.Extensions["errorCode"] = errorCode;
    pd.Extensions["traceId"] = traceId;

    if (!string.IsNullOrWhiteSpace(correlationId))
      pd.Extensions["correlationId"] = correlationId;

    return pd;
  }
}

Step 3 — Wire it up in Program.cs

using System.Diagnostics;
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Middleware
builder.Services.AddSingleton<CorrelationIdMiddleware>();

// ProblemDetails (automatically adds traceId/correlationId on results that use ProblemDetails)
builder.Services.AddProblemDetails(options =>
{
  options.CustomizeProblemDetails = ctx =>
  {
    ctx.ProblemDetails.Extensions["traceId"] =
      Activity.Current?.TraceId.ToString() ?? ctx.HttpContext.TraceIdentifier;

    var correlationId = ctx.HttpContext.Items[CorrelationIdMiddleware.HeaderName]?.ToString();
    if (!string.IsNullOrWhiteSpace(correlationId))
      ctx.ProblemDetails.Extensions["correlationId"] = correlationId;
  };
});

var app = builder.Build();

// Correlation ID must be early so it’s present during exception handling
app.UseMiddleware<CorrelationIdMiddleware>();

// Global exception handling: log + ProblemDetails response
app.UseExceptionHandler(errorApp =>
{
  errorApp.Run(async context =>
  {
    var ex = context.Features.Get<IExceptionHandlerFeature>()?.Error;

    var logger = context.RequestServices.GetRequiredService<ILoggerFactory>()
      .CreateLogger("GlobalExceptionHandler");

    var traceId = Activity.Current?.TraceId.ToString() ?? context.TraceIdentifier;
    var correlationId = context.Items[CorrelationIdMiddleware.HeaderName]?.ToString();

    logger.LogError(ex,
      "Unhandled exception. traceId={TraceId} correlationId={CorrelationId} method={Method} path={Path}",
      traceId, correlationId, context.Request.Method, context.Request.Path);

    var problem = new ProblemDetails
    {
      Status = StatusCodes.Status500InternalServerError,
      Title = "Unexpected error",
      Detail = "Contact support with the traceId/correlationId.",
      Type = "https://httpstatuses.com/500"
    };

    problem.Extensions["errorCode"] = "UNHANDLED_ERROR";
    problem.Extensions["traceId"] = traceId;
    if (!string.IsNullOrWhiteSpace(correlationId))
      problem.Extensions["correlationId"] = correlationId;

    context.Response.StatusCode = problem.Status.Value;
    context.Response.ContentType = "application/problem+json";
    await context.Response.WriteAsJsonAsync(problem);
  });
});

app.MapControllers();
app.Run();

Step 4 — Use it in a controller (example)

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("v1/orders")]
public class OrdersController : ControllerBase
{
  private readonly IOrdersRepository _repo;

  public OrdersController(IOrdersRepository repo) => _repo = repo;

  [HttpGet("{id:guid}")]
  public async Task<IActionResult> Get(Guid id, CancellationToken ct)
  {
    if (id == Guid.Empty)
    {
      var pd = ApiProblems.Create(
        HttpContext,
        status: StatusCodes.Status400BadRequest,
        title: "Invalid order id",
        detail: "Order id must be a non-empty GUID.",
        errorCode: "INVALID_ORDER_ID");

      return BadRequest(pd);
    }

    var order = await _repo.Get(id, ct); // if this throws, global handler catches it
    if (order is null)
    {
      var pd = ApiProblems.Create(
        HttpContext,
        status: StatusCodes.Status404NotFound,
        title: "Order not found",
        detail: "No order exists for the provided id.",
        errorCode: "ORDER_NOT_FOUND");

      return NotFound(pd);
    }

    return Ok(order);
  }
}

public interface IOrdersRepository
{
  Task<object?> Get(Guid id, CancellationToken ct);
}

What the client sees (why this reduces tickets)

A client error response becomes immediately actionable:

{
  "type": "https://httpstatuses.com/404",
  "title": "Order not found",
  "status": 404,
  "detail": "No order exists for the provided id.",
  "errorCode": "ORDER_NOT_FOUND",
  "traceId": "2c5f9d8b7f0a0d9e3f2c7f0b0a1b2c3d",
  "correlationId": "9f5c2e2d7a5a4e0f8f4e4b7c8e2d1a9b"
}

Support win: the customer can paste correlationId/traceId into a ticket, and you can find the exact request in Application Insights immediately.

Developer win: the errorCode is stable and can be handled in code (retry, fix payload, show UI message).

Operational benefits (what you’ll notice in production)

• Faster incident resolution: “find the failing request” becomes trivial.
• Lower ticket volume: better validation and predictable errors reduce confusion.
• Better client behavior: consistent status codes and error codes encourage correct retries and handling.
• Higher trust: external consumers perceive the API as stable and professional.

Hope you enjoyed the article. Happy Programming.

Memory-Saving Techniques to Boost Performance in ASP.NET Core Web APIs

 When an ASP.NET Core Web API starts slowing down under load, the root cause is often not “CPU is too high” — it’s memory pressure. Rising allocations trigger frequent garbage collections (GC), increased latency, and sometimes a steadily growing working set that ends in restarts or out-of-memory events (especially in containers).

This article walks through practical, high-impact memory-saving techniques for ASP.NET Core Web APIs and ties them together with a real-life style example of optimizing a “Orders” endpoint in an e-commerce system.

Why memory matters in Web APIs

Every request creates objects: DTOs, strings, collections, EF Core tracking graphs, serialized JSON buffers, logs, etc. If your API allocates more per request than necessary, you’ll see:

• Higher latency (GC pauses)
• Lower throughput (more time collecting than doing work)
• Memory spikes during traffic bursts
• Unstable performance over time (working set growth)

The goal isn’t “use no memory” — it’s to allocate less per request, avoid buffering large payloads, and keep caches bounded so memory stays predictable.

Real-life example scenario: “Orders API” under load

Context: An e-commerce platform exposes:

GET /api/orders/search?customerId=…

Traffic pattern:

• 200–500 requests/sec during peak
• Many clients ask for large date ranges
• A small percentage of customers have tens of thousands of orders

Symptoms:

• P95 latency jumps from 120ms to 900ms during peak
• Gen 2 GCs become frequent
• Memory usage climbs after each traffic spike
• Occasional container restarts

The “before” implementation (common anti-patterns)

Typical issues:

• Loading full entity graphs
• Tracking enabled for read endpoints
• Materializing full lists in memory
• Returning massive payloads without pagination

[HttpGet("search")]
public async Task<IActionResult> Search(Guid customerId)
{
    var orders = await _db.Orders
        .Include(o => o.Items)
        .Include(o => o.Payments)
        .Where(o => o.CustomerId == customerId)
        .OrderByDescending(o => o.CreatedAt)
        .ToListAsync();

    var dto = orders.Select(o => new OrderDto
    {
        Id = o.Id,
        CreatedAt = o.CreatedAt,
        Total = o.Total,
        Items = o.Items.Select(i => new ItemDto { /* ... */ }).ToList()
    }).ToList();

    return Ok(dto);
}

This looks harmless, but at scale it causes:

• Large allocations for List<>, nested List<>, DTO graphs
• EF Core tracking overhead (stores snapshots, references, fixup)
• Bigger JSON serialization buffers
• Higher GC pressure and latency

The optimized version: memory-saving changes that matter

Below are the highest-impact changes for memory and performance.

1) Always paginate large result sets

If your endpoint can return “all orders,” it will eventually return “too many orders.”

Rule of thumb: enforce a maximum pageSize, even for internal APIs.

[HttpGet("search")]
public async Task<IActionResult> Search(Guid customerId, int page = 1, int pageSize = 50)
{
    page = Math.Max(page, 1);
    pageSize = Math.Clamp(pageSize, 1, 200);

    // ...
}

Why this saves memory: you cap the number of entities/DTOs/materialized rows in memory at once.

2) Use AsNoTracking() for read-only queries

For read endpoints, EF Core tracking is often wasted memory.

var query = _db.Orders
    .AsNoTracking()
    .Where(o => o.CustomerId == customerId);

Why this saves memory: tracking creates internal data structures for every entity row. AsNoTracking() avoids them.

3) Project directly to DTOs (avoid loading entity graphs)

Instead of Include + mapping after the fact, shape the response in the database query.

var results = await _db.Orders
    .AsNoTracking()
    .Where(o => o.CustomerId == customerId)
    .OrderByDescending(o => o.CreatedAt)
    .Skip((page - 1) * pageSize)
    .Take(pageSize)
    .Select(o => new OrderSummaryDto
    {
        Id = o.Id,
        CreatedAt = o.CreatedAt,
        Total = o.Total,
        ItemCount = o.Items.Count
    })
    .ToListAsync();

Why this saves memory:

• You avoid materializing full Order, Items, Payments graphs
• You allocate fewer objects overall
• JSON serialization is smaller and faster

Bonus: this often reduces database load too.

4) Stream results for truly large exports (avoid buffering)

Some endpoints are inherently large (exports, reports). For those, don’t return huge JSON arrays in one shot.

Options:

• CSV export streamed to the response
• NDJSON streaming (one JSON object per line)
• IAsyncEnumerable streaming (careful with client expectations)

A CSV streaming example outline:

• Write headers
• Stream rows in batches
• Flush periodically

This keeps memory stable because you never hold the full dataset in memory.

5) Bound your caches (don’t “accidentally DOS yourself”)

Unbounded in-memory caching is a classic cause of memory growth.

If you use IMemoryCache, configure size limits and set size per entry:

• Enable SizeLimit
• Every entry must call SetSize(…)
• Use absolute expiration

Why this saves memory: the cache becomes self-limiting instead of growing with traffic patterns.

6) Avoid request/response body buffering unless required

Middleware or logging that reads the body often forces buffering. Buffering large payloads multiplies memory use during concurrency.

Guidance:

• Don’t enable request buffering globally
• Don’t log entire bodies in production
• Stream uploads/downloads

7) Logging: reduce hidden allocations

High-volume logging allocates:

• formatted strings
• structured state objects
• scope dictionaries

Prefer structured logs:

• Good: logger.LogInformation(“Fetched {Count} orders for {CustomerId}”, count, customerId);
• Avoid: interpolated strings in hot paths, or logging huge serialized objects

Putting it together: an “after” endpoint

Here’s a more memory-friendly version of the original endpoint:

[HttpGet("search")]
public async Task<ActionResult<PagedResult<OrderSummaryDto>>> Search(
    Guid customerId,
    int page = 1,
    int pageSize = 50)
{
    page = Math.Max(page, 1);
    pageSize = Math.Clamp(pageSize, 1, 200);

    var baseQuery = _db.Orders
        .AsNoTracking()
        .Where(o => o.CustomerId == customerId);

    var total = await baseQuery.CountAsync();

    var data = await baseQuery
        .OrderByDescending(o => o.CreatedAt)
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(o => new OrderSummaryDto
        {
            Id = o.Id,
            CreatedAt = o.CreatedAt,
            Total = o.Total,
            ItemCount = o.Items.Count
        })
        .ToListAsync();

    return Ok(new PagedResult<OrderSummaryDto>(data, total, page, pageSize));
}

public record OrderSummaryDto(Guid Id, DateTime CreatedAt, decimal Total, int ItemCount);

public record PagedResult<T>(IReadOnlyList<T> Data, int Total, int Page, int PageSize);

This version:

• Caps payload size
• Avoids tracking
• Avoids loading large graphs
• Allocates fewer objects per request

A quick checklist you can apply to most APIs

• Pagination everywhere for list endpoints
• AsNoTracking() for reads
• Projection (Select) instead of Include + mapping
• Streaming for exports and large payloads
• Bounded caching (size + expiration)
• No global body buffering
• Structured logging with controlled volume

How to validate improvements (what to measure)

To prove memory optimizations, track:

• Allocated bytes/sec
• Gen 0/1/2 GC counts
• P95/P99 latency
• Working set / private bytes
• Request rate under load

In practice, the biggest sign you’re winning is: lower allocations per request, fewer Gen2 collections, and stable memory during bursts.

Hope you like the article. Happy Programming.