←back to thread

Everything I know about good API design

(www.seangoedecke.com)
428 points ahamez | 4 comments | 24 Aug 25 19:10 UTC | HN request time: 0.001s | 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 #
JimDabell ◴[25 Aug 25 05:58 UTC] No.45010673[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 don’t really need to do that for REST APIs. If clients request application/vnd.foobar then you can always add application/vnd.foo.bar;version=2 later without planning this in advance.

replies(4): >>45011079 #>>45011820 #>>45018380 #>>45018873 #
1. lazyasciiart ◴[25 Aug 25 09:04 UTC] No.45011820[source]▶
Most REST APIs don’t support that. So you don’t need versioning for APIs that already have a request type specified.
replies(1): >>45012267 #
2. JimDabell ◴[25 Aug 25 10:14 UTC] No.45012267[source]▶
I’m not sure what you mean in the context of a discussion about how to design APIs. If you are the one designing an API, it’s up to you what you support.
replies(1): >>45029814 #
3. lazyasciiart ◴[26 Aug 25 17:41 UTC] No.45029814[source]▶
We call that baking them in from the very start of your application, which is what you claimed this didn’t need.
replies(1): >>45061456 #
4. JimDabell ◴[29 Aug 25 08:05 UTC] No.45061456{3}[source]▶
You don’t need to bake it in from the start.