DEV Community: Hilman Karyadi

Branching Strategy for API Versioning

Hilman Karyadi — Tue, 25 Feb 2025 14:34:14 +0000

Here’s a well-structured and formatted version of your branch naming convention, Git workflow, and API versioning steps:

✅ Recommended Branch Naming Convention

1️⃣ Main Development Branch

main or develop → Always contains the latest stable or development version.

2️⃣ Version-Specific Branches

release/v1.0 → First stable version
release/v2.0 → Second major update
feature/v3.0-new-payment-module → Feature branch for a new module in v3.0

3️⃣ Bug Fix & Hotfix Branches

hotfix/v1.0.1 → Hotfix for v1.0
bugfix/v2.1-db-performance → Bug fix for database performance in v2.1

🛠 Steps to Implement This in Git

1️⃣ Create a New Version Branch

To create a new branch for API version v2.0:

git checkout -b release/v2.0
git push origin release/v2.0

2️⃣ Switch Between API Versions

To work on v1.0:

git checkout release/v1.0

To work on v2.0:

git checkout release/v2.0

3️⃣ Merging API Updates

Once v2.0 is stable and ready for production, merge it into main:

git checkout main
git merge release/v2.0
git push origin main

📌 Branch Strategy Usage Guide

Scenario	Branch Name
Major API updates (breaking changes)	`release/vX.X`
New feature in a specific version	`feature/vX.X-feature-name`
Bug fixes in an older API version	`bugfix/vX.X-description`
Urgent hotfixes (security, critical bugs)	`hotfix/vX.X.X`

🚀 Setting Up API Versioning in `Ncs.Cqrs`

✅ Step 1: Create a New Git Branch for Version 1.0

Since you want to mark this as stable (v1.0), create a release branch:

git checkout -b release/v1.0
git push origin release/v1.0

✅ Step 2: Install API Versioning Packages

Inside your project folder, install the required API versioning dependencies:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning
dotnet add package Microsoft.AspNetCore.Mvc.Versioning.API explorer
dotnet add package Swashbuckle.AspNetCore

✅ Step 3: Configure API Versioning in `Program.cs`

Modify Program.cs to enable API versioning.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// 🔹 Add API Versioning
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),      // /api/v1/orders
        new QueryStringApiVersionReader("api-version"),  // ?api-version=1.0
        new HeaderApiVersionReader("X-API-Version")  // Header: X-API-Version: 1.0
    );
});

// 🔹 Configure API Explorer for Swagger
builder.Services.AddVersionedApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// 🔹 Configure Swagger
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(description.GroupName, new OpenApiInfo
        {
            Title = $"Ncs.Cqrs API {description.ApiVersion}",
            Version = description.ApiVersion.ToString()
        });
    }
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();

        foreach (var description in provider.ApiVersionDescriptions)
        {
            options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
        }
    });
}

app.UseAuthorization();
app.MapControllers();

app.Run();

✅ Step 4: Apply Versioning to Your Controllers

Modify your existing controllers by adding API version attributes.

OrdersController (v1.0 - Stable)

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
public class OrdersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v1 API" });
    }
}

Now, this controller only works for v1.0.

✅ Step 5: Push Changes to GitHub

Once you've added API versioning, push your changes to the release/v1.0 branch.

git add .
git commit -m "Added API versioning (v1.0 stable)"
git push origin release/v1.0

✅ Step 6: Test API Versioning

Test using URL Versioning

GET http://localhost:5000/api/v1/orders

Test using Query String

GET http://localhost:5000/api/orders?api-version=1.0

Test using Header

Header: X-API-Version: 1.0
GET http://localhost:5000/api/orders

🐞 Bug Fixing Workflow for `v1.0` API

Since v1.0 has already released, follow this workflow to create a hotfix branch.

1️⃣ Create a Hotfix Branch for v1.0

git checkout -b hotfix/v1.0.1 release/v1.0
git push origin hotfix/v1.0.1

2️⃣ Apply the Fix & Commit

git add .
git commit -m "🐞 Fixed issue with API Order update status in v1.0"
git push origin hotfix/v1.0.1

3️⃣ Merge the Fix into `release/v1.0`

git checkout release/v1.0
git merge hotfix/v1.0.1
git push origin release/v1.0

4️⃣ Merge the Fix into `main`

If main is still on v1.0, merge the fix into main:

git checkout main
git merge release/v1.0
git push origin main

5️⃣ Tag the Release (`v1.0.1`)

git tag v1.0.1
git push origin v1.0.1

6️⃣ Delete the Hotfix Branch (Cleanup)

git branch -d hotfix/v1.0.1
git push origin --delete hotfix/v1.0.1

🚀 Build & Publish API

Run in API project folder using Command Prompt:

dotnet build --configuration Release
dotnet publish --configuration Release --output C:\App\CanteenApi

🎯 Final Workflow Summary

Create Hotfix Branch → hotfix/v1.0.1
Apply Fix & Commit Changes
Merge into release/v1.0
Merge into main (if main is still on v1.0)
Tag Release (v1.0.1)
Delete Hotfix Branch

This ensures v1.0 remains stable while allowing fixes. 🚀

API Versioning in .NET 8

Hilman Karyadi — Mon, 24 Feb 2025 13:08:05 +0000

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package.

API Versioning in .NET 8

API versioning is essential for maintaining backward compatibility while evolving your API. In .NET 8, you can implement versioning using the Microsoft.AspNetCore.Mvc.Versioning package.

1. Why Use API Versioning?

Backward Compatibility: Ensures old clients can still use existing endpoints while new clients can leverage updated versions.
Incremental Changes: Allows adding new features without breaking existing functionality.
Deprecation Strategy: You can phase out old versions systematically.

2. Installing API Versioning Package

To enable API versioning in your .NET 8 Web API, install the following package:

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

3. Setting Up API Versioning

Modify Program.cs to register versioning in the Dependency Injection (DI) container:

Modify `Program.cs`

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Register API Versioning
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;  // Adds API version information in response headers
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0); // Default API version (1.0)
    options.ApiVersionReader = new UrlSegmentApiVersionReader(); // Versioning via URL
});

var app = builder.Build();

app.UseAuthorization();
app.MapControllers();

app.Run();

4. Applying API Versioning to Controllers

You can apply API versioning using attributes.

Using URL Path Versioning

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
public class OrdersV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v1 API" });
    }
}

[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("2.0")]
public class OrdersV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetOrders()
    {
        return Ok(new { Message = "Orders from v2 API - New version!" });
    }
}

Now, you can access:

Version 1 API: GET /api/v1/orders
Version 2 API: GET /api/v2/orders

5. Other API Versioning Strategies

Besides URL versioning, you can also use:

1. Query String Versioning

Modify Program.cs:

options.ApiVersionReader = new QueryStringApiVersionReader("api-version");

Then, call the API:

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

2. Header-Based Versioning

Modify Program.cs:

options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version");

Then, pass the version in headers:

GET /api/orders
X-API-Version: 2.0

6. Deprecating an API Version

You can mark an API version as deprecated using:

[ApiVersion("1.0", Deprecated = true)]

This will inform clients that version 1.0 is obsolete.

7. Versioning via Media Type (Content-Type)

Another approach is to specify the API version in the Accept header:

options.ApiVersionReader = new MediaTypeApiVersionReader("v");

Then, call the API with:

Accept: application/json; v=2.0

8. Combining Multiple Versioning Strategies

You can allow multiple versioning mechanisms:

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new QueryStringApiVersionReader("api-version"),
    new HeaderApiVersionReader("X-API-Version")
);

This allows clients to specify the version using URL, query string, or headers.

Conclusion

API versioning is critical for maintaining compatibility while evolving your API. In .NET 8, Microsoft.AspNetCore.Mvc.Versioning provides multiple strategies:

URL Path (/api/v1/orders)
Query String (?api-version=1.0)
Header (X-API-Version: 1.0)
Media Type (Accept: application/json; v=1.0)

Let's begin to write

Hilman Karyadi — Wed, 19 Feb 2025 12:33:54 +0000

Just the beginning, let's start writing

DEV Community: Hilman Karyadi

Branching Strategy for API Versioning

✅ Recommended Branch Naming Convention

1️⃣ Main Development Branch

2️⃣ Version-Specific Branches

3️⃣ Bug Fix & Hotfix Branches

🛠 Steps to Implement This in Git

1️⃣ Create a New Version Branch

2️⃣ Switch Between API Versions

3️⃣ Merging API Updates

📌 Branch Strategy Usage Guide

🚀 Setting Up API Versioning in Ncs.Cqrs

✅ Step 1: Create a New Git Branch for Version 1.0

✅ Step 2: Install API Versioning Packages

✅ Step 3: Configure API Versioning in Program.cs

✅ Step 4: Apply Versioning to Your Controllers

OrdersController (v1.0 - Stable)

✅ Step 5: Push Changes to GitHub

✅ Step 6: Test API Versioning

Test using URL Versioning

Test using Query String

Test using Header

🐞 Bug Fixing Workflow for v1.0 API

1️⃣ Create a Hotfix Branch for v1.0

2️⃣ Apply the Fix & Commit

3️⃣ Merge the Fix into release/v1.0

4️⃣ Merge the Fix into main

5️⃣ Tag the Release (v1.0.1)

6️⃣ Delete the Hotfix Branch (Cleanup)

🚀 Build & Publish API

🎯 Final Workflow Summary

API Versioning in .NET 8

API Versioning in .NET 8

1. Why Use API Versioning?

2. Installing API Versioning Package

3. Setting Up API Versioning

Modify Program.cs

4. Applying API Versioning to Controllers

Using URL Path Versioning

5. Other API Versioning Strategies

1. Query String Versioning

2. Header-Based Versioning

6. Deprecating an API Version

7. Versioning via Media Type (Content-Type)

8. Combining Multiple Versioning Strategies

Conclusion

Let's begin to write

🚀 Setting Up API Versioning in `Ncs.Cqrs`

✅ Step 3: Configure API Versioning in `Program.cs`

🐞 Bug Fixing Workflow for `v1.0` API

3️⃣ Merge the Fix into `release/v1.0`

4️⃣ Merge the Fix into `main`

5️⃣ Tag the Release (`v1.0.1`)

Modify `Program.cs`