0

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 : )

Tomorrow's Explorer
  • 65
  • 1
  • 14
  • 2
    Don't use the minor version number. Urls with a dot in them are a bitch. Just use the major version number `(/api/v1/controller/method)` – Reinstate Monica Cellio Oct 19 '18 at 11:51
  • I personally deem both as horrible by design ... A header telling what version you want would be more suited for REST applications as versiosn are neither resource access nor are they arguments relevant to the resource. **But to expand definition**, unstable URL paths is when stuff like `foo.com/items/1` may change to `foo.com/products/1`. You then should use the URL variant. – X39 Oct 19 '18 at 11:51
  • @X39: headers are horrible idea imho, as they are hard to transport, don't work with get queries you paste into browser and make using of tools like swagger unnecessarily hard or even impossible. Swagger/OpenAPI UI has a ready to use documentation and tools to send out requests from within the swagger ui, can't remember theres been an easy way to set headers globally – Tseng Oct 19 '18 at 11:57
  • @Tseng your whole reason is "The APIs and tools are crap" ... Headers are easy to transport (the actual content actually is more complicated then "moving" headers from clients to servers) Only thing i agree on is that it is harder to use them for "new" APIs ... But even then, you always can use eg. [nginx to setup subdomains for you and edit the header request version into it making `foo.com` to `v1.foo.com` etc.](https://stackoverflow.com/questions/11973047/adding-and-using-header-http-in-nginx) making that part problem-free again – X39 Oct 19 '18 at 12:03
  • 1
    If you gonna translate hosts or urls with an reverse proxy to headers, then you can also just directly use it in the application as part of the path. The whole point about stable vs unstable API paths is that the url path doesn't change. Adding "v1" to the domain also changes the stability of the client, since the url changed too. query parameters on the other side aren't strictly part of the url path, they are more like filters (hence its name: query string) `/api/products/2` or `/api/products/2?version=2` still point to the same resource (thats what REST is about: Resources) – Tseng Oct 19 '18 at 12:12
  • Paths aren't really important or relevant. You can follow the HATEOAS+HAL approach and add a service discovery resource to your API that provides a list of supported versions and the corresponding root resource, expose each API version through any resource, and then let clients pick which version (and resource) they'll adopt. With this approach you are free to use, say, GUIDs to specify the endpoint that supports a specific version, and even switch GUIDs between requests to the service discovery endpoint. – RAM Oct 22 '18 at 13:57

1 Answers1

1

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.

Jeffrey Stylos
  • 163
  • 7