Web API Versioning Using Accept Header

Back to: ASP.NET Web API Tutorial

Versioning your ASP.NET Web API using the Accept header is a powerful way to manage API evolution. This guide provides a detailed lesson on versioning your API using the Accept header, along with code examples.

Prerequisites

Before you start, ensure you have:

  1. A solid understanding of ASP.NET Web API.
  2. Visual Studio or a code editor of your choice.
  3. Familiarity with C# and HTTP concepts.

Step 1: Define Media Type for API Versions

  1. Decide on a media type format for representing API versions. A common convention is to use custom media types like application/vnd.myapi.v1+json for version 1 and application/vnd.myapi.v2+json for version 2.
  2. Document these media types in your API documentation to inform clients about the available versions.

Step 2: Implement Versioning Logic

  1. In your Web API project, create a versioning logic that inspects the Accept header of incoming requests to determine the requested version. You can achieve this using a custom MediaTypeMapping class.
using System;
using System.Net.Http.Formatting;
using System.Net.Http.Headers;
using System.Web.Http;
using System.Web.Http.Controllers;

public class VersionedMediaTypeMapping : MediaTypeMapping
{
    private readonly string _version;

    public VersionedMediaTypeMapping(string mediaType, string version)
        : base(mediaType)
    {
        _version = version;
    }

    public override double TryMatchMediaType(HttpRequestMessage request)
    {
        if (request == null)
        {
            throw new ArgumentNullException(nameof(request));
        }

        MediaTypeHeaderValue acceptHeader = request.Headers.Accept.FirstOrDefault();

        if (acceptHeader != null && acceptHeader.MediaType != null)
        {
            string[] acceptValues = acceptHeader.MediaType.Split('+');

            if (acceptValues.Length > 1 && acceptValues[1] == _version)
            {
                return 1.0;
            }
        }

        return 0.0;
    }
}

Step 3: Apply Versioning to Controllers

Apply the VersionedMediaTypeMapping to your API controllers to indicate which version(s) they support.

[RoutePrefix("api/myapi")]
public class MyApiController : ApiController
{
    [Route("data")]
    [HttpGet]
    [VersionedMediaType("application/vnd.myapi.v1+json", "v1")]
    [VersionedMediaType("application/vnd.myapi.v2+json", "v2")]
    public IHttpActionResult GetData()
    {
        // Your API action logic here, can be version-specific
    }
}

Step 4: Test API Versions

Test your API versions by making requests with the Accept header specifying the desired version.

GET https://yourapi.com/api/myapi/data
Accept: application/vnd.myapi.v2+json

Conclusion

By following this comprehensive guide, you’ve learned how to version your ASP.NET Web API using the Accept header. This method allows you to manage API evolution effectively and cater to different client versions. Custom media type mappings offer flexibility and fine-grained control over versioning, ensuring that your API remains versatile and backward-compatible.