DEV Community: Pankaj Singh

6 ASP.NET Core Web API mistakes I keep fixing, and the patterns I use instead

Pankaj Singh — Fri, 23 Oct 2026 04:34:08 +0000

I've spent about four and a half years building and maintaining ASP.NET Core APIs with SQL Server and Azure. A lot of that time goes into reading existing code, and the same handful of problems shows up again and again. None of them are exotic. They're the kind of thing that works fine in a demo and then bites you at 2 AM in production.

Here are six I see most, with the pattern I use instead. The code comes from a .NET 10 / EF Core 10 starter I maintain, but everything here also works on .NET 8 with small changes.

1. try/catch in every action (and stack traces in responses)

The symptom: every controller action is wrapped in try { ... } catch (Exception ex) { return BadRequest(ex.Message); }. Error formats differ between endpoints, real bugs come back as 400s, and sometimes ex.ToString() leaks a stack trace to the client.

The fix: throw meaningful exceptions from your services and turn them into responses in one place. Since .NET 8, IExceptionHandler is the clean hook for this:

public sealed class GlobalExceptionHandler(
    IProblemDetailsService problemDetailsService,
    ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        var problem = exception switch
        {
            ValidationException ve => CreateValidationProblem(ve),
            NotFoundException => new ProblemDetails { Status = 404, Title = "Resource not found", Detail = exception.Message },
            ConflictException => new ProblemDetails { Status = 409, Title = "Conflict", Detail = exception.Message },
            _ => new ProblemDetails { Status = 500, Title = "An unexpected error occurred" },
        };

        if (problem.Status >= 500)
        {
            logger.LogError(exception, "Unhandled exception for {Method} {Path}",
                httpContext.Request.Method, httpContext.Request.Path);
        }

        httpContext.Response.StatusCode = problem.Status ?? 500;
        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            ProblemDetails = problem,
            Exception = exception,
        });
    }
}

builder.Services.AddProblemDetails(o => o.CustomizeProblemDetails = ctx =>
{
    ctx.ProblemDetails.Extensions["traceId"] = ctx.HttpContext.TraceIdentifier;
});
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();

// ...
app.UseExceptionHandler();

Note the 500 branch: no Detail, no exception message. The client gets a generic RFC 9457 response plus a traceId it can send you, and the full exception goes to your logs. Controllers become one-liners:

[HttpGet("{id:guid}")]
public async Task<ActionResult<ProductDto>> Get(Guid id, CancellationToken ct) =>
    Ok(await products.GetAsync(id, ct));

2. List endpoints that return the whole table

The symptom: return await db.Products.ToListAsync();. It's fine with 50 rows. With 200,000 rows it's slow, uses a lot of memory, and EF tracks every entity it loaded even though you're only going to serialize them.

The fix has four parts: no tracking, project to a DTO, always order, and page with a hard limit.

IQueryable<Product> q = db.Products.AsNoTracking();

if (!string.IsNullOrWhiteSpace(query.Search))
{
    var term = query.Search.Trim();
    q = q.Where(p => p.Name.Contains(term) || p.Sku.Contains(term));
}

q = query.SortDescending
    ? q.OrderByDescending(p => p.CreatedAtUtc)
    : q.OrderBy(p => p.CreatedAtUtc);

return await q
    .Select(p => new ProductDto(p.Id, p.Name, p.Sku, p.Price, p.Stock))
    .ToPagedResultAsync(query.Page, query.PageSize, ct);

The paging helper is small:

public static async Task<PagedResult<T>> ToPagedResultAsync<T>(
    this IQueryable<T> query, int page, int pageSize, CancellationToken ct = default)
{
    var total = await query.CountAsync(ct);
    var items = await query.Skip((page - 1) * pageSize).Take(pageSize).ToListAsync(ct);
    return new PagedResult<T>(items, page, pageSize, total);
}

Two details people miss:

Order before Skip/Take. Without an OrderBy, SQL Server doesn't promise any row order, so page 2 can repeat rows from page 1. EF Core even logs a warning about it.
Cap the page size. Otherwise someone sends ?pageSize=1000000 and you're back to square one. I validate it with FluentValidation, so a bad value becomes a clean 400 through the handler from section 1:

RuleFor(x => x.Page).GreaterThanOrEqualTo(1);
RuleFor(x => x.PageSize).InclusiveBetween(1, PagedRequest.MaxPageSize); // 100

Select into a DTO also means SQL only fetches the columns you need, and you never serialize navigation properties by accident.

3. Ignoring the CancellationToken

The symptom: async methods without a CancellationToken, or a token accepted and never passed on. When a user closes the tab or a client times out, the query keeps running on the database anyway.

The fix is boring but effective. Take the token in the action and pass it all the way down:

[HttpGet]
public async Task<ActionResult<PagedResult<ProductDto>>> List(
    [FromQuery] ProductQuery query, CancellationToken ct) =>
    Ok(await products.ListAsync(query, ct));

ASP.NET Core binds CancellationToken parameters to HttpContext.RequestAborted automatically. Inside the service, pass ct to every EF call (ToListAsync(ct), FirstOrDefaultAsync(..., ct), SaveChangesAsync(ct)). EF Core forwards cancellation to the database provider, so an abandoned request stops doing work instead of finishing a query nobody will read.

4. DateTime values that lose their "UTC-ness"

The symptom: you save DateTime.UtcNow, read it back, and the JSON has no Z. The frontend treats it as local time, and everyone in India sees timestamps 5.5 hours off. That happens because SQL Server's datetime2 doesn't store a kind, so EF returns DateTimeKind.Unspecified.

The fix: store UTC everywhere and tell EF to mark values as UTC when it reads them. One loop in OnModelCreating covers every entity:

var utc = new ValueConverter<DateTime, DateTime>(
    v => v,
    v => DateTime.SpecifyKind(v, DateTimeKind.Utc));

foreach (var property in modelBuilder.Model.GetEntityTypes().SelectMany(t => t.GetProperties()))
{
    if (property.ClrType == typeof(DateTime))
    {
        property.SetValueConverter(utc);
    }
}

(Add a matching converter for DateTime?.) While you're in the DbContext, set audit fields in one place and use TimeProvider instead of DateTime.UtcNow, so tests can control the clock:

public override Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
{
    var now = _clock.GetUtcNow().UtcDateTime;
    foreach (var entry in ChangeTracker.Entries<BaseEntity>())
    {
        if (entry.State == EntityState.Added) entry.Entity.CreatedAtUtc = now;
        else if (entry.State == EntityState.Modified) entry.Entity.UpdatedAtUtc = now;
    }
    return base.SaveChangesAsync(cancellationToken);
}

If you need to keep the original offset, use DateTimeOffset instead. For audit timestamps, UTC plus a converter is usually enough.

5. Config errors that only show up on the first request

The symptom: a missing JWT signing key or a typo in a config section. The app starts fine, health checks pass, and then the first login request throws. Worse, the "fix" is often to commit the secret to appsettings.json.

The fix: bind config to a typed options class, add validation attributes, and validate at startup:

public sealed class JwtOptions
{
    public const string SectionName = "Jwt";

    [Required] public string Issuer { get; set; } = string.Empty;
    [Required] public string Audience { get; set; } = string.Empty;

    [Required, MinLength(32)]
    public string SigningKey { get; set; } = string.Empty;

    [Range(1, 1440)] public int AccessTokenMinutes { get; set; } = 15;
}

services.AddOptions<JwtOptions>()
    .Bind(configuration.GetSection(JwtOptions.SectionName))
    .ValidateDataAnnotations()
    .ValidateOnStart();

With ValidateOnStart(), a bad deploy fails right away with a clear message instead of failing later on some user's request. Keep the secret itself out of git: dotnet user-secrets on your machine, and an environment variable like Jwt__SigningKey or Azure Key Vault in production.

Pair this with two health endpoints, so your host knows the difference between "process is up" and "database is reachable":

services.AddHealthChecks().AddDbContextCheck<AppDbContext>("database", tags: ["ready"]);

app.MapHealthChecks("/health/live", new HealthCheckOptions { Predicate = _ => false });
app.MapHealthChecks("/health/ready", new HealthCheckOptions { Predicate = c => c.Tags.Contains("ready") });

6. Login endpoints with no rate limit

The symptom: /api/auth/login accepts unlimited attempts from one IP. That's an open invitation to password guessing.

ASP.NET Core has had built-in rate limiting since .NET 7, so you don't need a package:

services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.AddPolicy("auth", ctx => RateLimitPartition.GetFixedWindowLimiter(
        $"auth:{ctx.Connection.RemoteIpAddress}",
        _ => new FixedWindowRateLimiterOptions
        {
            PermitLimit = 10,
            Window = TimeSpan.FromSeconds(60),
            QueueLimit = 0,
        }));
});

app.UseAuthentication();
app.UseRateLimiter();
app.UseAuthorization();

Then put [EnableRateLimiting("auth")] on login, register and refresh. One caveat: behind a reverse proxy or load balancer, RemoteIpAddress is the proxy unless you configure Forwarded Headers middleware. Otherwise every user shares one bucket.

The short version

One exception handler, ProblemDetails everywhere, no stack traces in responses.
AsNoTracking, DTO projection, OrderBy, and capped paging on every list.
Pass the CancellationToken all the way to EF.
UTC in, UTC out, with a value converter and TimeProvider.
Typed options with ValidateOnStart, secrets outside git, live and ready health checks.
Rate-limit anything that takes a password.

I packaged these patterns, plus JWT with refresh tokens, roles, Swagger, Serilog, Docker and tests, as a .NET 10 API starter. If you have an existing ASP.NET Core project with one of these problems and would rather hand it off, I also take small fix-it jobs on Fiverr and Kwork.

Which mistake did I miss? Tell me in the comments.

Parts of this post were drafted with AI assistance and reviewed by me.

One config file, zero runtime JS: how I built a fast Astro + Tailwind 4 template for small business sites

Pankaj Singh — Fri, 23 Oct 2026 04:33:45 +0000

Most small business websites I get asked about have the same shape: a home page, an about page, a list of products or services, a page for each product, and a contact page with a phone number, a WhatsApp button and a map. The owner wants it fast, wants it to show up on Google, and wants to change the phone number without calling a developer.

I'm a backend .NET developer by day, so my instinct was to treat this like a data problem. The pages are just views over one object. In this post I'll walk through how I set that up with Astro 7 and Tailwind CSS 4, using real code from the template I built. You can reuse every pattern here in your own project.

1. Put all the content in one typed file

Everything a visitor sees lives in src/data/site.ts: name, colours, contact details, SEO text, products, testimonials and navigation. Pages and components only read from it.

// src/data/site.ts
export interface Product {
  /** URL slug: /products/<slug>. Lowercase, hyphens only. */
  slug: string;
  name: string;
  category: string;
  summary: string;
  description: string[];
  image: string;
  price?: string;
  specs?: Record<string, string>;
  features?: string[];
  featured?: boolean;
}

export const site = {
  name: 'Sharma Precision Tools',
  shortName: 'SPT',
  url: 'https://www.example.com',
  theme: {
    primary: '#1d4ed8',
    primaryDark: '#1e3a8a',
    accent: '#f59e0b',
    dark: '#0f172a',
  },
  contact: {
    phone: '+91 98000 00000',
    whatsapp: '919800000000',
    // ...
  },
  products: [
    {
      slug: 'circular-slitting-knives',
      name: 'Circular Slitting Knives',
      category: 'Blades',
      // ...
    },
  ] satisfies Product[],
  // seo, home, about, nav, testimonials...
};

Two small TypeScript details make this pleasant:

satisfies Product[] checks every product against the interface but keeps the literal types. A typo in a field name fails the build instead of failing silently in production.
Optional fields (price?, specs?) let one product have a spec table and another have none. The components just check whether the field exists.

Why not a CMS or Astro content collections? For a 6-page site that the owner edits a few times a year, one file is easier to explain than a dashboard. If the site grows, moving products into a content collection is a small refactor because the shape is already typed.

2. Generate a page per product with `getStaticPaths`

The product detail route is a single file, src/pages/products/[slug].astro. Astro calls getStaticPaths at build time and writes one HTML file per product:

---
import Base from '../../layouts/Base.astro';
import { site, whatsappLink, type Product } from '../../data/site';

export function getStaticPaths() {
  return site.products.map((product) => ({
    params: { slug: product.slug },
    props: { product },
  }));
}

const { product } = Astro.props as { product: Product };
const related = site.products
  .filter((p) => p.slug !== product.slug && p.category === product.category)
  .slice(0, 3);
const ask = whatsappLink(`Hello! I'd like a quote for: ${product.name}`);
---

Add an object to the array and you get a new page, a new sitemap entry and a "related products" block. Nobody touches routing.

The WhatsApp link is a tiny helper in the same data file. In India, WhatsApp is often the main way customers contact a business, so it matters more than the contact form:

export function whatsappLink(text: string = site.contact.whatsappMessage): string {
  return `https://wa.me/${site.contact.whatsapp}?text=${encodeURIComponent(text)}`;
}

export function telLink(): string {
  return `tel:${site.contact.phone.replace(/[^\d+]/g, '')}`;
}

The phone is stored once in a human-friendly format (+91 98000 00000), and telLink() strips it down for the tel: link.

3. Brand colours as CSS variables, exposed to Tailwind 4

I wanted owners to change colours in site.ts, not in CSS. Tailwind 4's @theme inline makes this clean. The layout writes the colours onto <html> as CSS variables:

---
// src/layouts/Base.astro
const t = site.theme;
const brandVars = `--brand-primary:${t.primary};--brand-primary-dark:${t.primaryDark};--brand-accent:${t.accent};--brand-dark:${t.dark};`;
---
<html lang={site.lang} style={brandVars}>

The stylesheet then maps those variables to Tailwind theme colours:

/* src/styles/global.css */
@import "tailwindcss";

@theme inline {
  --color-primary: var(--brand-primary);
  --color-primary-dark: var(--brand-primary-dark);
  --color-accent: var(--brand-accent);
  --color-dark: var(--brand-dark);
}

Now bg-primary, text-primary-dark and hover:bg-primary-dark all work as normal utilities, and they follow whatever hex value is in the config. inline matters here: it tells Tailwind to use the var(...) reference directly in the generated utility instead of resolving it to a fixed value at build time.

Tailwind 4 also needs no tailwind.config.js. The whole Astro config is this:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
import tailwindcss from '@tailwindcss/vite';
import { site } from './src/data/site.ts';

export default defineConfig({
  site: process.env.SITE_URL || site.url,
  compressHTML: true,
  integrations: [sitemap()],
  vite: { plugins: [tailwindcss()] },
});

The SITE_URL override is handy for demo or staging deploys, so canonical links and the sitemap point at the right domain without editing the config.

4. Ship (almost) no JavaScript

Astro ships zero JS by default, and the easiest way to keep it fast is to not undo that. Two places where people usually reach for JS:

The mobile menu. A <details> element opens and closes without a single line of script, and it's keyboard accessible out of the box:

<details class="relative md:hidden">
  <summary class="grid h-10 w-10 cursor-pointer list-none place-items-center rounded-lg border border-slate-300 [&::-webkit-details-marker]:hidden" aria-label="Open menu">
    <!-- hamburger svg -->
  </summary>
  <ul class="absolute right-0 mt-2 w-56 rounded-xl border border-slate-200 bg-white p-2 shadow-lg">
    {site.nav.map((item) => (
      <li><a href={item.href} class="block rounded-lg px-3 py-2">{item.label}</a></li>
    ))}
  </ul>
</details>

The contact form. The form has three modes set in config: netlify (Netlify Forms), action (post to Formspree or your own API) and whatsapp. Only the WhatsApp mode needs a script, and it's about 15 lines. It reads FormData, joins the fields into a message and opens wa.me. That's the only client-side JS on the whole site, and it only loads on the contact page.

Other things that helped performance:

System font stack. No web font download. Inter is first in the stack, so it's used if the visitor already has it.
Fixed image dimensions. Every <img> has width and height, plus loading="lazy" and decoding="async" on cards. That prevents layout shift.
Reduced motion. A prefers-reduced-motion block turns off transitions and smooth scrolling for people who ask for it.

When I ran Lighthouse on the home, product and contact pages of the demo, all four categories scored 100. Your numbers will depend on your images and hosting, so test your own build.

5. SEO that comes from the same config

Base.astro builds the canonical URL, Open Graph and Twitter tags from site.seo and the current path. It also adds LocalBusiness JSON-LD on every page:

const canonical = new URL(Astro.url.pathname, Astro.site ?? site.url).href;

const businessLd = {
  '@context': 'https://schema.org',
  '@type': 'LocalBusiness',
  name: site.name,
  url: site.url,
  telephone: site.contact.phone,
  address: site.contact.address,
  sameAs: Object.values(site.social).filter(Boolean),
};

<script type="application/ld+json" set:html={JSON.stringify(businessLd)} />

Product pages pass an extra Product schema through a jsonLd prop. @astrojs/sitemap writes sitemap-index.xml, and robots.txt is a tiny endpoint, so it always points at the right domain:

// src/pages/robots.txt.ts
import type { APIRoute } from 'astro';

export const GET: APIRoute = ({ site }) => {
  const sitemap = new URL('sitemap-index.xml', site).href;
  return new Response(`User-agent: *\nAllow: /\n\nSitemap: ${sitemap}\n`, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
};

The sameAs filter is a small win. Empty social links in the config disappear from both the footer and the structured data.

6. Deploy for free

npm run build outputs a plain static dist/ folder, so any static host works:

Netlify: a netlify.toml sets npm run build, dist and Node 22. Netlify Drop (drag the dist folder into the browser) works if you don't use Git.
Vercel: import the repo. It detects Astro automatically.
Cloudflare Pages: pick the Astro preset and set NODE_VERSION to 22.

Astro 7 needs Node 22.22 or newer, so set that on your host or the build will fail early. An .nvmrc file and the engines field in package.json keep local machines and CI in line.

Wrapping up

The core idea is simple: one typed data file, pages that are pure views over it, and no JavaScript unless a feature truly needs it. That split makes the site easy for a non-developer to edit and hard for it to get slow over time.

If you want to see it running, the demo is at astro-business-template-demo.vercel.app. I've also packaged the full template with all six pages, the three form modes and deploy docs, on my Payhip store, in case you'd rather not build it from scratch.

Questions or a better pattern for any of this? I'd like to hear it in the comments.