0

Here is my problem and first question I struggle to find an answer to:

  • I have an API based on a specific standard
  • One of the endpoints looks like this: POST/ petstore.swagger.io/v2/pet
  • Clients expect this URL to be in this exact format and use have /v2/, since version number in URL reflects implemented standard
  • I have a bug in this API, and fixing it would mean introducing a breaking change. Clients application will stop working if the change is made
  • If I introduce a breaking change, I must allow both versions (with and without a bug fix) to run in parallel, to let clients to comfortably adapt

So far, I couldn't come with anything better then introducing a minor version to URL. But this on its own is a deviation from the standard and a breaking change.

How to version APIs which follow a standard, but deviated from it? While that standard requires a specific version numbers to be used in URLs?

Thank you

Rytis D
  • 1
  • 2
  • Anyway, you will have to introduce a URL that is different from the current one. I would introduce V3 with the breaking changes. Mark V2 as depricated. You can return supported version header in the response. Keep V2 live until there are no requests. – Kishan Vaishnav May 15 '20 at 03:55
  • Thank you for replying. Simply incrementing version number in URL is probably least favorite option for me, as it would result in permanent deviation from standard. Let's say I increment v2 -> v3 to release a fix for breaking change. But once guidelines for v3 of the standard are released I will be in even tougher situation. So far my best candidate is introducing a minor version number v2 -> v2.1, where 2 refers to standard version and 1 to my bug fix. I was tempted to introduce another version number in (!)optional(!) header, but it feels like a terrible idea. Any thoughts? – Rytis D May 16 '20 at 15:03
  • If the bug is not a critical bug then you can introduce v2.1. Introducing a minor version means that v2.1 is recommended but you can implement v2.0 as well. – Kishan Vaishnav May 18 '20 at 06:27

0 Answers0