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:
- A solid understanding of ASP.NET Web API.
- Visual Studio or a code editor of your choice.
- Familiarity with C# and HTTP concepts.
Step 1: Define Media Type for API Versions
- 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 andapplication/vnd.myapi.v2+json
for version 2. - Document these media types in your API documentation to inform clients about the available versions.
Step 2: Implement Versioning Logic
- 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 customMediaTypeMapping
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.