←back to thread

Everything I know about good API design

(www.seangoedecke.com)
428 points ahamez | 3 comments | 24 Aug 25 19:10 UTC | HN request time: 0.206s | source
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 #
andix ◴[24 Aug 25 23:31 UTC] No.45008763[source]▶
I don't see any harm in adding versioning later. Let's say your api is /api/posts, then the next version is simply /api/v2/posts.
replies(1): >>45008980 #
choult ◴[25 Aug 25 00:07 UTC] No.45008980[source]▶
It's a problem downstream. Integrators weren't forced to include a version number for v1, so the rework overhead to use v2 will be higher than if it was present in your scheme to begin.
replies(2): >>45009191 #>>45013434 #
1. pixl97 ◴[25 Aug 25 00:51 UTC] No.45009191[source]▶
This here, it's way easier to grep a file for /v1/ and show all the api endpoints then ensure you haven't missed something.
replies(2): >>45010335 #>>45013456 #
2. cmcconomy ◴[25 Aug 25 04:53 UTC] No.45010335[source]▶
grep for /* and omit /v2 ?
3. andix ◴[25 Aug 25 13:10 UTC] No.45013456[source]▶
Edit:

^/api(/(?!v[0-9]).)?$ is v1

^/api/v2(/.)?$ is v2

It's really not an issue in any case, it just itches your brain, because is not as neat as you would like it to be.