Introduction

REST APIs are the backbone of modern web and mobile applications. They enable communication between clients, servers, third-party services, and microservices. As APIs evolve, developers often introduce new features, modify existing endpoints, or deprecate outdated functionality. Without proper planning, these changes can break existing client applications.

At the same time, APIs must be protected against unauthorized access, data leaks, and common security vulnerabilities. Building secure APIs while maintaining backward compatibility is essential for delivering reliable applications.

In this article, you'll learn how to build secure REST APIs using ASP.NET Core, implement API versioning, and follow best practices that improve security, maintainability, and scalability.

Why API Security Matters

An unsecured API can expose sensitive business data and become a target for attackers.

Implementing proper security measures helps:

Security should be considered from the beginning of the development process rather than added later.

What Is API Versioning?

API versioning is the practice of managing changes to an API without breaking existing client applications.

Instead of replacing an existing API, developers create a new version while allowing older versions to continue working.

For example:

/api/v1/products
/api/v2/products

This approach allows clients to migrate at their own pace.

Common API Versioning Strategies

ASP.NET Core supports several versioning approaches.

URL Versioning

The version number is included in the URL.

Example:

GET /api/v1/products

Advantages:

Query String Versioning

The version is passed as a query parameter.

Example:

GET /api/products?api-version=1.0

This approach avoids changing endpoint URLs but is less commonly used.

Header Versioning

Clients specify the version in an HTTP header.

Example:

api-version: 1.0

This keeps URLs clean but requires clients to manage custom headers.

Configure API Versioning

ASP.NET Core makes it easy to configure API versioning.

Example:

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);

    options.AssumeDefaultVersionWhenUnspecified = true;

    options.ReportApiVersions = true;
});

This configuration sets a default version and reports supported API versions in response headers.

Create Versioned Controllers

Controllers can support multiple API versions.

Example:

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok();
    }
}

This controller responds to requests made to version 1 of the API.

Secure APIs with JWT Authentication

JSON Web Tokens (JWT) are one of the most common authentication mechanisms for REST APIs.

Typical authentication flow:

  1. User signs in.

  2. Server validates credentials.

  3. JWT token is generated.

  4. Client sends the token with each request.

  5. API validates the token before processing the request.

This approach enables secure, stateless authentication.

Use HTTPS

Always expose REST APIs over HTTPS.

HTTPS encrypts data transmitted between the client and server, protecting sensitive information such as:

Never expose production APIs over plain HTTP.

Validate Input Data

Never trust data received from clients.

Always validate:

Input validation helps prevent invalid requests and reduces the risk of security vulnerabilities.

Apply Authorization

Authentication identifies users, while authorization determines what they are allowed to do.

ASP.NET Core supports role-based authorization.

Example:

[Authorize(Roles = "Administrator")]
public IActionResult Delete(int id)
{
    return Ok();
}

Only users assigned to the Administrator role can access this endpoint.

Practical Example

Imagine you're building an online banking API.

Version 1 includes:

Version 2 introduces:

Instead of replacing Version 1, both versions remain available.

Security measures include:

Existing mobile applications continue working while newer clients adopt the latest API version.

Protect Against Common Threats

Secure APIs should also defend against common attack vectors.

Consider implementing:

These protections improve the overall security posture of your API.

Best Practices

When building secure versioned APIs, follow these recommendations:

Following these practices helps build secure and maintainable APIs.

Common Use Cases

Secure versioned APIs are widely used in:

These applications often require long-term API compatibility while maintaining strong security.

Things to Consider

Before publishing your API, keep these points in mind:

Building security into the API from the start is more effective than trying to add it later.

Conclusion

Building secure REST APIs in ASP.NET Core requires a combination of strong authentication, proper authorization, input validation, HTTPS, and thoughtful API versioning. By implementing these practices, you can protect your applications from common security threats while ensuring existing clients continue to work as your API evolves.

Whether you're developing internal services or public-facing APIs, a well-designed versioning strategy combined with robust security measures creates a reliable foundation for scalable and maintainable applications. Investing in these best practices early helps reduce future maintenance efforts and improves the overall experience for API consumers.