C# Academy · Lesson

API Versioning Strategies

Version via URL, header, and query string.

Lesson 1 of 413 steps

API Versioning Strategies is a free C# Academy lesson on CoddyKit. This is lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the C# Academy learning path, and your progress syncs across the web and the CoddyKit app. The C# Academy course includes 4 lessons in total.

Why Version an API?

Once clients depend on your API, you cannot break its contract. Versioning lets you ship breaking changes in a new version while old clients keep working against the old one.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

URL Path Versioning

The most visible strategy puts the version in the path. It is unambiguous and easy to route, browse and cache.

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

Query String Versioning

The version travels as a query parameter. URLs stay stable and a missing parameter can default to the latest or a fixed version.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Header Versioning

A custom request header carries the version, keeping the URL clean. The downside: it is invisible in a browser address bar and harder to test by hand.

GET /api/products
X-Api-Version: 2.0

Media Type Versioning

Also called content negotiation. The version is embedded in the Accept header's media type. It is the most RESTful but least discoverable option.

GET /api/products
Accept: application/json;v=2.0

Comparing the Strategies

Each strategy trades discoverability against URL cleanliness:

URL path: most discoverable, clutters URLs.
Query string: stable URLs, easy defaults.
Header: clean URLs, hidden from browsers.
Media type: purest REST, hardest to use.

// Many teams pick URL path for public APIs

Semantic Versioning of APIs

API versions are usually major-only (v1, v2). Reserve minor versions for additive, non-breaking changes that old clients can ignore.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Deprecation

Never remove an old version abruptly. Mark it deprecated, advertise a sunset date, and signal it to clients via headers.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Default Version

Decide what happens when a client sends no version. Common choices: assume the latest, assume v1, or reject the request. Being explicit avoids surprises.

// Strategy: unversioned request -> treat as v1.0

Versioning the Right Things

Version the contract (routes, request/response shapes), not internal implementation details. A v2 endpoint can share most business logic with v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Mixing Strategies

ASP.NET Core's versioning library can read the version from several sources at once, letting clients pick whichever is convenient. You will configure this next.

// Accept version from URL OR header OR query

Quick Check

Test your understanding of versioning strategies.

Answer it in the interactive lesson

Recap

You surveyed API versioning strategies:

URL path, query string, header, and media type.
Each trades discoverability against URL cleanliness.
Version the contract, deprecate gracefully, and define a default.

Next: configuring Asp.Versioning in ASP.NET Core.

Free to start

Learn C# with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 93
Lessons: 346

Start learning free View the full course

Frequently Asked Questions

Is the “API Versioning Strategies” lesson free?

Yes — the full text of “API Versioning Strategies” is free to read here on the web. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the C# Academy course, upgrade to CoddyKit PRO. The C# Academy course includes 4 lessons in total.

What will I learn in “API Versioning Strategies”?

Version via URL, header, and query string. You practise C# Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start C# Academy?

No prior experience is required. C# Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 1 of 4.

How long does the “API Versioning Strategies” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this C# Academy lesson?

Yes. Every C# Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to C# Academy