CODEWITHSUNDEEP
c#jsonapiarchitecture
atp03
atp03

Reputation: 3699

How to version an api endpoint in .net

We're setting up a bunch of json web services in ASP.NET which is served as .ashx (custom handlers) files. An example would be:

/mobile/json.ashx

We'd like to implement some form of versioning as well as to not break apps which has not upgraded. So we led down this path:

/mobile/json.ashx?v=1.0

Now, of course we have have a switch statement in our custom handlers to manage the differences between api version but this doesn't sound like a very maintainable solution to me.

What are the best practises for this kind of set up and what options are available for version control?

Thanks

Upvotes: 0

Views: 847

Answers (1)

Timothy Shields
Timothy Shields

Reputation: 79441

Placing the version in the query parameters (that is, after the ?) suggests to the user that each endpoint is individually versioned. I would avoid this.

If your web service is structured such that there are larger logical units that are being individually versioned, then I would go with something like this:

/api1/1.0/some/endpoint
/api1/1.1/some/endpoint
/api2/1.0/some/other/endpoint
/api2/2.0/some/other/endpoint
...

The version portion of the path comes directly after the thing which is being versioned. This suggests to the user that everything underneath /api1/1.1/ is version 1.1 of API 1 and everything underneath /api2/2.0/ is version 2.0 of API 2.

If someone entirely omits the version portion of the path, the latest version should be implied. So /api2/some/other/endpoint would map to, say, /api2/2.0/some/other/endpoint.

If you're using ASP.NET MVC, all of this can be accomplished very easy using route configuration in the RegisterRoutes method in Global.asax.cs. For example:

routes.MapRoute("api1/1.1", "api1/1.1/some/endpoint",
    new { controller = "Api1_1_1", action = "SomeEndpoint" });

where you have a controller class Api1_1_1 with method SomeEndpoint.

Upvotes: 2

Related Questions