Practical NET and Software Architecture Tips: Mastering API Versioning and Change Management

By /

Listen to this Post

2025-02-15

API versioning is a critical aspect of modern software architecture, especially when building RESTful APIs. One of the cleanest approaches to API versioning is media type versioning. Here’s how it works:

  1. Specify the API version in the Accept header: This allows clients to request a specific version of the API by including the version in the `Accept` header of the HTTP request.
  2. Server routes the request to the appropriate API: Based on the version specified in the `Accept` header, the server routes the request to the corresponding API implementation.

However, versioning is only a means to an end. The ultimate goal is effective change management. A well-designed API should minimize the need for versioning by implementing backward-compatible changes and clear communication with API consumers.

To dive deeper into these concepts, check out the full course on Pragmatic REST APIs: Learn more.

Practical Code Examples

Here are some practical examples to implement media type versioning in a .NET API:

// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new MediaTypeApiVersionReader("v");
});
}

// Controllers
[ApiVersion("1.0")]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("Version 1.0");
}

[ApiVersion("2.0")]
[Route("api/[controller]")]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("Version 2.0");
}

Linux and Windows Commands for API Management

  • Linux: Use `curl` to test API versioning: 
    curl -H "Accept: application/vnd.api.v1+json" http://localhost:5000/api/products
curl -H "Accept: application/vnd.api.v2+json" http://localhost:5000/api/products

  • Windows: Use PowerShell to test APIs:

    Invoke-WebRequest -Uri "http://localhost:5000/api/products" -Headers @{"Accept"="application/vnd.api.v1+json"}
Invoke-WebRequest -Uri "http://localhost:5000/api/products" -Headers @{"Accept"="application/vnd.api.v2+json"}

What Undercode Say

API versioning is a crucial part of software architecture, but it should not be the primary focus. Instead, prioritize change management to ensure backward compatibility and seamless transitions for API consumers. Media type versioning is a clean and effective approach, but it requires careful implementation. Always test your APIs thoroughly using tools like `curl` or PowerShell commands. For more advanced topics, explore the Pragmatic REST APIs course linked above. Remember, the best APIs evolve gracefully without breaking changes, and effective communication with your API consumers is key to achieving this. Keep experimenting with different versioning strategies and refine your approach based on real-world feedback. Happy coding!

References:

Hackers Feeds, Undercode AIFeatured Image

Related Posts: