CODEWITHSUNDEEP
c#asp.net-coreversioning
Tomorrow's Explorer
Tomorrow's Explorer

Reputation: 75

Versioning formats for REST API

I try get into versioning strategies for REST API's following Microsoft REST API Guidelines and trying to utilize for my ASP.NET Core solution.

From the guide :

Two options for specifying the version of a REST API request are supported:

  • Embedded in the path of the request URL, at the end of the service root: https://api.contoso.com/v1.0/products/users

  • As a query string parameter of the URL: https://api.contoso.com/products/users?api-version=1.0

Guidance for choosing between the two options is as follows:

...

  1. Services that guarantee the stability of their REST API's URL paths, even through future versions of the API, MAY adopt the query string parameter mechanism. This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.
  2. Services that cannot ensure URL path stability across future versions MUST embed the version in the URL path.

I think that I don't quite understand what does 'cannot evolve' means in -

This means the naming and structure of the relationships described in the API cannot evolve after the API ships, even across versions with breaking changes.

Could you please give a little expanded definition ?

And do you have any example of Services that cannot ensure URL path stability across future versions ?

Thank you : )

Upvotes: 1

Views: 1893

Answers (1)

Jeffrey Stylos
Jeffrey Stylos

Reputation: 173

The Microsoft guidelines are recommending not using query parameters to control major versions if you anticipate changes to the resource names in the URLs themselves.

With path parameter versioning you could have:

https://api.contoso.com/v1.0/products/users https://api.contoso.com/v2.0/items/customers

where with query parameters, they recommend changing the resource names, where some resources would only support some version parameters.

As @Archer says, the most common practice seems to be to use a major version without a dot or subversion, and query parameter versions are rare except for version date parameters like FourSquare's (https://developer.foursquare.com/docs/api/configuration/versioning), which is typically used in addition to a major path version, and typically controls smaller API changes than resource name changes.

Upvotes: 2

Related Questions