3

I need to expose a new version of an API method as I cannot afford to have breaking changes to the existing one.

Existing : http://www.test.com/api/v1/customer/{id}

New : http://www.test.com/api/v2/customer/{id}

I have read about the different ways to do versioning and strategies applied. What I need to know is :

1) How to manage code base while I apply versioning?

2) Is it a must to have all the API's in all the versions?

I am working on ASP.NET web API and I have more than 100 endpoints in my current version and I am looking to avoid code duplication and find the best way to keep the code manageable.

Any help would be appreciable.

Jose Francis
  • 950
  • 13
  • 28
  • It depends how your endpoints are actually setup but symlinks/ shortcuts are a potential route to avoid duplicating files, or alternatively the host config of your webserver. As for 2), are you referring to only having the new/ changed ones in version 2? It also depends if your API has a directory or not. E.g. where `http://www.test.com/api/v2/` lists all of the available endpoints and optionally usage information. If that's the case, duplicating everything from v1 becomes less necessary - the directory can just list out the v1 endpoints. – Luke Briggs Feb 08 '17 at 04:52
  • @Luke Could you elaborate on the "symlinks/ shortcuts" you mentioned and as for 2), I was asking about the best practice/standard way of doing this. – Jose Francis Feb 08 '17 at 05:06
  • 1
    For example, if `api/v2/customer/` is a directory, you could create a symlink (which act like a special kind of shortcut) so `api/v1/customer/` points at the same place. Apply to all other unchanged endpoints. Note that it's being done backwards - the actual files exist in the most recent version of the API. – Luke Briggs Feb 08 '17 at 05:24
  • As for best practice, does your API have a directory of available endpoints, like [let's encrypt as an example](https://acme-v01.api.letsencrypt.org/directory)? The version number itself only really applies to the directory itself if you do this - the API gives no guarantee that the URLs will be in any way consistent. – Luke Briggs Feb 08 '17 at 05:31
  • Also, it's worth noting that the broader category which that example loosely fits into is _"self documenting API's"_. [Here's another API with a directory](https://txroot.opentrans.fr/v1/) which much better fits in that self-documenting category. Versioning these ones is just a case of releasing a new endpoint directory. – Luke Briggs Feb 08 '17 at 05:38

0 Answers0