Catalog My learning Blog
Full-Stack Developer Course: React, .NET and SQL Server · Phase 3 · Lesson 25 · 6 min read

ASP.NET Core API Versioning Without Breaking React

On this page
  1. Learning Objective
  2. Concept Explanation
  3. Worked Example: URL Versions, a Sunset Header and an Expand and Contract Rename
  4. Real-World Examples
  5. Review Questions & Answers

Learning Objective

Distinguish breaking from non-breaking changes, choose a versioning scheme, implement versioned endpoints with Asp.Versioning, and manage deprecation and retirement, including the unique problem that old cached React bundles keep calling your API after you deploy.

Concept Explanation

Once an API has clients you do not control, its contract is a promise. Changes fall into two kinds. Non-breaking changes are additive: a new endpoint, a new optional field in a response, a new optional query parameter. Existing clients keep working. Breaking changes remove or rename a field, change a type, make an optional input required, change the meaning of a value, or tighten validation so previously valid requests fail. Clients built against the old contract then fail. The first discipline of evolution is to prefer additive changes and to write clients as tolerant readers that ignore fields they do not recognize, which React code does naturally when it destructures only what it needs.

Web frontends have a twist that mobile and server clients share only partially. When you deploy a new version of the API and a new React bundle together, users who already have the site open, or who have a cached bundle or service worker, continue running the old JavaScript against the new API for hours or days. So even in a single-team, single-repo product, you have two versions in production at once. The rule follows: the API must remain compatible with the previous frontend release for at least one deployment cycle, and breaking changes need a multi-step rollout, adding the new form, moving clients across, then removing the old form.

When a breaking change is unavoidable, you introduce a new version. There are three common places to put it. A URL segment, such as /api/v2/notes, is the most visible and easiest to route, cache, and test in a browser. A header, such as a custom version header, keeps URLs clean but is harder to see and debug. A media type parameter follows the purist model but is the most awkward for tooling. URL versioning is the pragmatic default for most product APIs, and the Asp.Versioning.Http package supports all three, plus per-version OpenAPI documents and deprecation metadata.

Versions have a lifecycle, and the security part of it is retirement. Announce deprecation with response headers, in particular Sunset, defined in RFC 8594, which carries the date after which the endpoint will stop working, and by tracking who still calls old versions in your logs. Then actually turn them off. Old versions are a well-known source of vulnerabilities, because they are maintained less, may lack newer authorization checks and validation, and are forgotten. OWASP lists improper inventory management, including old API versions left running, as one of the top API risks, so retirement is a security task, not just housekeeping.

ChangeBreaking?Safe way to do it
Add an optional response fieldNoJust add it
Add a new endpointNoJust add it
Remove or rename a response fieldYesAdd the new field, deprecate the old, remove later
Change a field's typeYesNew field or new version
Make an optional request field requiredYesNew version, or accept and default
Tighten validationPotentiallyAnnounce, monitor rejects, roll out gradually

Worked Example: URL Versions, a Sunset Header and an Expand and Contract Rename

The registration sets up two versions and a deprecation for v1. The DTO section shows a field rename done over two releases without breaking the running React clients.

C#
// dotnet add package Asp.Versioning.Http
builder.Services.AddApiVersioning(o =>
{
    o.DefaultApiVersion = new ApiVersion(1, 0);
    o.AssumeDefaultVersionWhenUnspecified = false;        // require clients to say which version
    o.ReportApiVersions = true;                           // adds api-supported-versions headers
    o.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(o => o.GroupNameFormat = "'v'VVV");

var versions = app.NewApiVersionSet()
    .HasDeprecatedApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

var api = app.MapGroup("/api/v{version:apiVersion}").WithApiVersionSet(versions);

api.MapGet("/notes/{id:int}", (int id) => /* v1 shape */ Results.Ok(new { id, text = "..." }))
   .MapToApiVersion(1, 0)
   .AddEndpointFilter(async (ctx, next) =>
   {
       ctx.HttpContext.Response.Headers["Sunset"] = "Wed, 31 Dec 2026 23:59:59 GMT";
       ctx.HttpContext.Response.Headers["Link"] = "</api/v2/notes>; rel=\"successor-version\"";
       return await next(ctx);
   });

api.MapGet("/notes/{id:int}", (int id) => /* v2 shape */ Results.Ok(new { id, title = "...", body = "..." }))
   .MapToApiVersion(2, 0);
C#
// Expand and contract: renaming "text" to "body" without breaking cached React bundles.

// Release 1 (expand): return BOTH fields. Old clients read text, new clients read body.
public record NoteDtoV1(int Id, string Title, string Body, string Text);   // Text mirrors Body

// Release 2: ship the React change that reads body only. Wait until logs show old bundles are gone.

// Release 3 (contract): remove the deprecated field.
public record NoteDto(int Id, string Title, string Body);

The React side helps by treating unknown fields as harmless and by checking for the new field first with a fallback to the old one during the overlap. Monitoring how many requests still use the old shape, for instance through a custom log property, tells you when the contract step is safe.

A field rename ships across three releases. Old cached React bundles keep working during the overlap, and the old field is removed only after logs show no client still reads it.
A field rename ships across three releases. Old cached React bundles keep working during the overlap, and the old field is removed only after logs show no client still reads it.

Real-World Examples

  • Stripe pins each account to the API version that was current when it first made a request, with dates as version names such as 2020-08-27, and lets developers upgrade deliberately or test a new version per request using a header. Backward-incompatible changes only ever ship in a new dated version, which is why integrations written years ago still work.
  • GitHub introduced calendar-based REST API versions selected with an X-GitHub-Api-Version header, with 2022-11-28 as the first, and documents that breaking changes will only be released in new versions with advance notice and support for older versions for at least 24 months. It is a concrete example of a published deprecation policy that gives client developers a predictable timeline.
Key TakeawaysPrefer additive, tolerant changes, and remember that cached React bundles mean two frontend versions are live after every deploy. When a break is unavoidable, use expand and contract or a new version with a clear deprecation header and timeline, then genuinely retire old versions, because forgotten versions are an attack surface.

Review Questions & Answers

Clients read the field by name, so a client expecting the old name receives undefined or fails when the new response omits it. The safe path is to return both names for a period, migrate clients to the new one, and only then remove the old. Additive steps let old and new clients coexist during the transition.

After a deploy, users who already loaded the app keep running the previous JavaScript, and cached bundles or service workers can persist that for days. Those clients call the new API with the old contract expectations. The API therefore needs to support the previous frontend release until it has effectively disappeared from traffic.

It tells clients the date after which a resource is expected to stop responding, in a machine-readable form defined by RFC 8594. Tooling and monitoring can surface it before the deadline, and it makes the retirement schedule explicit in every response instead of relying on emails that get missed.

Old versions are rarely updated, so they may lack newer authorization checks, input validation, and rate limits, and they are often absent from documentation and monitoring. Attackers look specifically for them because they are the weakest path to the same data. Retiring versions on schedule removes that hidden attack surface.