[claw-el]

If there is a breaking change forced upon in the future, can’t we use a different name for the function?

[soulofmischief]

A versioned API allows for you to ensure a given version has one way to do things and not 5, 4 of which are no longer supported but can't be removed. You can drop old weight without messing up legacy systems.

[Bjartr]

See the many "Ex" variations of many functions in the Win32 API for examples of exactly that!

[jahewson]

/api/postsFinalFinalV2Copy1-2025(1)ExtraFixed

[pixl97]

Discoverability.

/v1/downloadFile

/v2/downloadFile

Is much easier to check for a v3 then

/api/downloadFile

/api/downloadFileOver2gb

/api/downloadSignedFile

Etc. Etc.

[echelon]

I have only twice seen a service ever make a /v2.

It's typically to declare bankruptcy on the entirety of /v1 and force eventual migration of everyone onto /v2 (if that's even possible).

[claw-el]

Isn’t having the name (e.g. Over2gb) easier to understand than just saying v2? This is in the situation where there is breaking changes forced upon v1/downloadFile.

[ks2048]

If you only break one or two functions, it seems ok. But, some change in a core data type could break everything, so adding a prefix "/v2/" would probably be cleaner.

[CharlesW]

You could, but it just radically increases complexity in comparison to "version" knob in a URI, media type, or header.