Overview
This repository adds a small but opinionated layer on top of Asp.Versioning for APIs that negotiate versions through media types instead of route segments or query-string parameters. It focuses on making that style of versioning behave as one coherent setup, where service registration, explorer metadata, header parsing, and failure translation follow the same rules.
Because the repository contains a single package, its value is less about package selection and more about tightening one specific API versioning model. The goal is to remove repeated glue code around Accept-header parsing and to keep versioning failures consistent across the ASP.NET Core pipeline.
Concepts
The concepts in this repository all revolve around one boundary: version negotiation should be configured once, then applied consistently both when requests are read and when failures are written back to clients.
Media-type version negotiation
The central concept is version selection through an Accept header parameter rather than through routes or query strings. Codebelt.Extensions.Asp.Versioning contributes RestfulApiVersionReader, which narrows Asp.Versioning's media-type reader to an explicit allow-list of media types, and RestfulApiVersioningOptions, which lets the same configuration choose both the parameter name and the accepted header values. That pairing matters because the package treats header parsing as an API contract, not just a parser detail.
Unified service registration
The repository also treats versioning setup as one registration unit. In Codebelt.Extensions.Asp.Versioning, AddRestfulApiVersioning ties together Asp.Versioning, MVC integration, and ApiExplorer configuration so the selected parameter name, default API version, selector type, and explorer group naming stay aligned. The result is a narrower setup surface for REST-style APIs that want OpenAPI grouping and version reader behavior to come from the same options object.
Consistent error translation
A second repository-level concern is how versioning failures move through the pipeline after negotiation fails. Codebelt.Extensions.Asp.Versioning handles this in two places: service registration can either keep the built-in RFC 7807 response path or translate problem-details payloads into Cuemon HTTP exceptions, and UseRestfulApiVersioning can intercept bare status-code responses and raise mapped exceptions instead. Together those hooks make versioning errors easier to route through the same exception-handling and formatter infrastructure as the rest of an API.
Usage guidance
Adopt this repository when your API already uses Asp.Versioning and you want media-type based version negotiation to be the default model across registration, explorer output, and error handling. It is a good fit when the Accept header is part of the API contract and your pipeline already benefits from exception-based response formatting.
If your API uses URL or query-string versioning, or if you prefer the plain Asp.Versioning defaults without extra response translation, this repository adds an opinionated layer you do not need. In that case, configure Asp.Versioning directly and keep the versioning surface closer to the framework defaults.