Everything I know about good API design

(www.seangoedecke.com)

Show context

pixl97 ◴[24 Aug 25 21:54 UTC] No.45008158[source]▶

While the author doesn't seem to like version based APIs very much, I always recommend baking them in from the very start of your application.

You cannot predict the future and chances are there will be some breaking change forced upon you by someone or something out of your control.

replies(7): >>45008436 #>>45008763 #>>45009169 #>>45009423 #>>45009623 #>>45010511 #>>45010673 #

1. claw-el ◴[24 Aug 25 22:36 UTC] No.45008436[source]▶

>>45008158 #

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

replies(7): >>45008467 #>>45008545 #>>45008580 #>>45008683 #>>45009012 #>>45009205 #>>45009223 #

2. ◴[24 Aug 25 22:41 UTC] No.45008467[source]▶

>>45008436 (TP) #

3. soulofmischief ◴[24 Aug 25 22:55 UTC] No.45008545[source]▶

>>45008436 (TP) #

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.

4. CharlesW ◴[24 Aug 25 23:01 UTC] No.45008580[source]▶

>>45008436 (TP) #

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

5. Bjartr ◴[24 Aug 25 23:14 UTC] No.45008683[source]▶

>>45008436 (TP) #

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

6. jahewson ◴[25 Aug 25 00:13 UTC] No.45009012[source]▶

>>45008436 (TP) #

/api/postsFinalFinalV2Copy1-2025(1)ExtraFixed

7. pixl97 ◴[25 Aug 25 00:55 UTC] No.45009205[source]▶

>>45008436 (TP) #

Discoverability.

/v1/downloadFile

/v2/downloadFile

Is much easier to check for a v3 then

/api/downloadFile

/api/downloadFileOver2gb

/api/downloadSignedFile

Etc. Etc.

replies(2): >>45009539 #>>45009597 #

8. ks2048 ◴[25 Aug 25 00:58 UTC] No.45009223[source]▶

>>45008436 (TP) #

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.

9. echelon ◴[25 Aug 25 02:04 UTC] No.45009539[source]▶

>>45009205 #

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

replies(2): >>45009627 #>>45009660 #

10. claw-el ◴[25 Aug 25 02:18 UTC] No.45009597[source]▶

>>45009205 #

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.

11. pixl97 ◴[25 Aug 25 02:27 UTC] No.45009627{3}[source]▶

>>45009539 #

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.

12. bigger_cheese ◴[25 Aug 25 02:35 UTC] No.45009660{3}[source]▶

>>45009539 #

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/

It talks about avoiding this by designing future APIs using a flags bitmask to allow API to be extended in future.

↑