Giters

dotnet / aspnet-api-versioning

Provides a set of libraries which add service API versioning to ASP.NET Web API, OData with ASP.NET Web API, and ASP.NET Core.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Question: Hiding a version that's not ready for release

dhavv opened this issue · comments

commented

Hi, so I currently have an API endpoints that is currently on version 1
I'm planning to make new features so it will be on version 2. But I'm wondering what's the most recommended way to hide a version that's not ready for release and in development?
(For example this version 2 is probably be ready after couple of pull requests to main branch)
So in the mean time I want to hide it first to not accidentally be used by clients.
I was thinking that maybe I can just comment out ApiVersionAttribute(2) but I don't think it's a clean way to do it

I'm using Web API OData (.NET Framework)

commented

There are several approaches to address this issue. The first question is really about whether you want to hide the API or just restrict who can use it? Pre-releases are a supported concept; for example:

[Authorize("EarlyAdopters")]
[ApiVersion(2.0, "preview.1")]
[RoutePrefix("awesome")]
public class AwesomeController : ApiController
{
    [Route]
    public IHttpActionResult Get() => StatusCode(HttpStatusCode.OK);
}

GET /awesome?api-version=2.0-preview.1 indicates that it is a preview and is only accessible to EarlyAdopters. If any one else tries to access the API, they will receive 403.

If you don't want anyone to access the API beyond the development team, then the best way to deal with that is likely a different version control system branching. Rather than have pull requests go to main, they should go to branch release/2.0 or something like that. Once everything is tested, validated, and ready to go to main, then - and only then - a lead/manager/etc merges release/2.0 to main. This keeps things cleanly separated without a bunch of code churn and trickery.