ASP.NET Core Web API: A Practical Business Guide

Quick answer: ASP.NET Core Web API is Microsoft’s framework for building HTTP services in C#. On .NET Core 3.1, the current long-term support release, you get controllers with attribute routing, automatic model validation, built-in dependency injection, System.Text.Json for fast serialization and cross-platform hosting on Windows, Linux or containers. It is a strong fit when your business already runs on Microsoft technology or needs a typed, well-tooled backend for web and mobile apps, integrations and internal systems.

When ASP.NET Core Web API makes sense

An API sits between your data and the things that use it: a website, a mobile app, a partner system, a reporting tool. If you are new to the idea, our plain-English guide to what is an API is a good starting point.

ASP.NET Core Web API is a good choice when:

Your team or vendor works in C# and Visual Studio
You use SQL Server, Azure or other Microsoft services
You are replacing older ASP.NET Web Forms, WCF or classic ASP Web API 2 services
You want strong typing, mature tooling and long-term support from Microsoft
Performance matters; ASP.NET Core is fast and handles high request volumes well on modest hardware

If you are weighing it against other stacks, our comparison of .NET vs Node.js covers the trade-offs.

What changed with ASP.NET Core 3.x

If your last experience was ASP.NET Web API 2 on .NET Framework, a few things are different:

Cross-platform. Runs on Linux and in Docker as well as Windows and IIS.
Unified MVC and Web API. One framework; controllers inherit from ControllerBase for APIs.
Endpoint routing is the default in 3.0 and later.
System.Text.Json replaces Newtonsoft.Json as the default serializer, which is faster but stricter. You can still add Newtonsoft support with a package if you depend on its features.
Generic host and a cleaner Startup class handle configuration, logging and dependency injection.

.NET Core 3.1 is an LTS release, supported for three years from December 2019, which makes it a sensible base for business systems today.

The basic shape of a Web API project

Create a project with dotnet new webapi or the Visual Studio template. The key pieces are:

Program.cs builds and runs the host
Startup.cs registers services and configures the request pipeline
Controllers/ holds API controllers
appsettings.json holds configuration

A simple controller looks like this:

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orders;

    public OrdersController(IOrderService orders)
    {
        _orders = orders;
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<OrderDto>> Get(int id)
    {
        var order = await _orders.FindAsync(id);
        if (order == null) return NotFound();
        return order;
    }

    [HttpPost]
    public async Task<ActionResult<OrderDto>> Create(CreateOrderDto input)
    {
        var created = await _orders.CreateAsync(input);
        return CreatedAtAction(nameof(Get), new { id = created.Id }, created);
    }
}

The [ApiController] attribute turns on helpful behavior: automatic 400 responses when model validation fails, binding complex types from the request body, and problem details responses for errors.

Designing endpoints people can use

Framework features do not make an API pleasant to work with. Design does.

Use nouns for resources (/api/orders, /api/customers/42/invoices) and HTTP methods for actions.
Return the right status codes: 200, 201 with a location, 204, 400, 401, 403, 404, 409.
Use consistent naming and date formats.
Page large lists rather than returning thousands of rows.
Keep request and response models (DTOs) separate from database entities so you can change one without breaking the other.

Our guide to REST API design goes deeper on these choices, and API versioning explains how to change an API without breaking existing clients. The Microsoft.AspNetCore.Mvc.Versioning package adds URL, header or query string versioning to ASP.NET Core.

Data access with Entity Framework Core 3.1

Most business APIs read and write a database. EF Core 3.1 is the usual choice:

Define entities and a DbContext
Register it in Startup with services.AddDbContext<AppDbContext>(...)
Use migrations to manage schema changes
Inject the context into services, not directly into controllers, to keep logic testable

A few EF Core 3.x habits worth knowing:

EF Core 3.0 stopped silently evaluating unsupported LINQ on the client. Queries that cannot be translated to SQL now throw, which surfaces slow queries early instead of hiding them.
Use AsNoTracking() for read-only queries.
Project to DTOs with Select rather than loading full entity graphs.
Watch for N+1 queries when including related data.

For heavy reporting queries, Dapper alongside EF Core is a common and practical combination.

Authentication and authorization

Most business APIs need to know who is calling.

JWT bearer tokens are the common pattern for single-page apps and mobile apps. Add Microsoft.AspNetCore.Authentication.JwtBearer, configure the issuer and audience, and protect controllers with [Authorize].
An identity provider such as Azure Active Directory, Azure AD B2C, IdentityServer4 or Auth0 issues tokens so you do not build login yourself.
API keys suit simple server-to-server integrations, but treat them like passwords and rotate them.
Policies and roles handle authorization: [Authorize(Policy = "CanApproveInvoices")].

If OAuth terms feel unclear, our explainer on OAuth breaks down flows and tokens.

Always use HTTPS, validate all input, and never return stack traces to clients in production.

Validation and errors

Use data annotations ([Required], [StringLength], [Range]) or FluentValidation for complex rules. With [ApiController], invalid models return a 400 with a problem details body automatically.

For unexpected errors, add exception handling middleware that logs the details and returns a consistent problem details response. Clients should be able to handle every error the same way.

Documentation with Swagger

Swashbuckle or NSwag generate an OpenAPI document and an interactive Swagger UI from your controllers. Add XML comments to describe endpoints and models. Good documentation saves hours of back-and-forth with front-end developers and partners. Treat the docs as part of the product: examples, error codes and authentication steps belong there, not in someone’s inbox.

Testing

Unit tests for services and business rules with xUnit, NUnit or MSTest and a mocking library.
Integration tests with WebApplicationFactory from Microsoft.AspNetCore.Mvc.Testing, which spins up the API in memory and lets you call real endpoints.
Manual and exploratory testing with Postman or the Swagger UI.

We covered testing patterns in .NET unit testing.

Hosting and deployment

Options include:

IIS on Windows Server with the ASP.NET Core Hosting Bundle
Azure App Service for managed hosting with deployment slots
Linux with Kestrel behind Nginx
Docker containers on any host that runs them

Set up health checks (services.AddHealthChecks()), structured logging and application monitoring such as Application Insights. Automate builds and deployments with Azure DevOps Pipelines or a similar CI tool so releases are repeatable.

Common mistakes in business APIs

Exposing database entities directly, which leaks fields and couples clients to your schema
No paging on list endpoints
Inconsistent error formats
Secrets in appsettings.json checked into source control instead of user secrets, environment variables or Azure Key Vault
No versioning plan until the first breaking change
Long-running work inside requests instead of a background queue

FAQ

Should we upgrade from ASP.NET Web API 2?

If the old service is stable and rarely changes, there is no rush. If you are adding features, need Linux hosting or want better performance, moving to ASP.NET Core 3.1 is worth planning.

Is ASP.NET Core Web API only for Windows?

No. It runs on Windows, Linux and macOS, and in containers.

Can it serve a React or Angular front end?

Yes. A common setup is a JavaScript front end calling an ASP.NET Core API, hosted separately or together.

How long does a typical business API take to build?

It depends on the number of resources, integrations and rules. A focused API with a handful of resources can be weeks; an integration hub across several systems takes longer.

Build services that last

ASP.NET Core Web API on .NET Core 3.1 gives you a fast, well-supported foundation for business services. Pair it with good design, clear docs and automated tests. If you need an API built or an older .NET service modernised, see our custom development services.

ASP.NET Core Web API: Building Services for Your Business Apps