4 ms·

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

deleted 1y ago
[deleted]
soulofmischief 1y ago
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.
CharlesW 1y ago
You could, but it just radically increases complexity in comparison to "version" knob in a URI, media type, or header.
Bjartr 1y ago
See the many "Ex" variations of many functions in the Win32 API for examples of exactly that!
jahewson 1y ago
/api/postsFinalFinalV2Copy1-2025(1)ExtraFixed
pixl97 1y ago
Discoverability. /v1/downloadFile /v2/downloadFile Is much easier to check for a v3 then /api/downloadFile /api/downloadFileOver2gb /api/downloadSignedFile Etc. Etc.
- echelon 1y ago
  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).
  - pixl97 1y ago
    I work for a company that has an older api so it's defined in the header, but we're up to v6 at this point. Very useful for changes that have happened over the years.
  - bigger_cheese 1y ago
    A lot of the Unix/Linux Syscall api has a version 2+ For example dup(), dup2(), dup3() and pipe(), pipe2() etc LWN has an article: https://lwn.net/Articles/585415/ https://lwn.net/Articles/585415/ It talks about avoiding this by designing future APIs using a flags bitmask to allow API to be extended in future.
- claw-el 1y ago
  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 1y ago
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.

deleted 1y ago

[deleted]

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.

CharlesW 1y ago

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

Bjartr 1y ago

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

jahewson 1y ago

/api/postsFinalFinalV2Copy1-2025(1)ExtraFixed

pixl97 1y ago

Discoverability. /v1/downloadFile /v2/downloadFile Is much easier to check for a v3 then /api/downloadFile /api/downloadFileOver2gb /api/downloadSignedFile Etc. Etc.

echelon 1y ago
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).
- pixl97 1y ago
  I work for a company that has an older api so it's defined in the header, but we're up to v6 at this point. Very useful for changes that have happened over the years.
- bigger_cheese 1y ago
  A lot of the Unix/Linux Syscall api has a version 2+ For example dup(), dup2(), dup3() and pipe(), pipe2() etc LWN has an article: https://lwn.net/Articles/585415/ https://lwn.net/Articles/585415/ It talks about avoiding this by designing future APIs using a flags bitmask to allow API to be extended in future.
claw-el 1y ago
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 1y ago

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.