DEV Community

Cover image for Branching Strategy for API Versioning
Hilman Karyadi
Hilman Karyadi

Posted on

Branching Strategy for API Versioning

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
Enter fullscreen mode Exit fullscreen mode

2️⃣ Switch Between API Versions

To work on v1.0:

git checkout release/v1.0
Enter fullscreen mode Exit fullscreen mode

To work on v2.0:

git checkout release/v2.0
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

📌 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
Enter fullscreen mode Exit fullscreen mode

✅ 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
Enter fullscreen mode Exit fullscreen mode

✅ 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();
Enter fullscreen mode Exit fullscreen mode

✅ 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" });
    }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

✅ Step 6: Test API Versioning

Test using URL Versioning 

GET http://localhost:5000/api/v1/orders
Enter fullscreen mode Exit fullscreen mode

Test using Query String 

GET http://localhost:5000/api/orders?api-version=1.0
Enter fullscreen mode Exit fullscreen mode

Test using Header 

Header: X-API-Version: 1.0
GET http://localhost:5000/api/orders
Enter fullscreen mode Exit fullscreen mode

🐞 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

5️⃣ Tag the Release (v1.0.1) 

git tag v1.0.1
git push origin v1.0.1
Enter fullscreen mode Exit fullscreen mode

6️⃣ Delete the Hotfix Branch (Cleanup) 

git branch -d hotfix/v1.0.1
git push origin --delete hotfix/v1.0.1
Enter fullscreen mode Exit fullscreen mode

🚀 Build & Publish API

Run in API project folder using Command Prompt:

dotnet build --configuration Release
dotnet publish --configuration Release --output C:\App\CanteenApi
Enter fullscreen mode Exit fullscreen mode

🎯 Final Workflow Summary

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

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

Top comments (0)