←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: 0s | 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. 946789987649 ◴[25 Aug 25 07:01 UTC] No.45011079[source]▶
If you use something like an OpenAPI generator and want to have different DTOs in your version 2, then you cannot do what you suggested.
replies(2): >>45011742 #>>45024298 #
2. JimDabell ◴[25 Aug 25 08:53 UTC] No.45011742[source]▶
You can specify multiple media types in OpenAPI.
3. jamietanna ◴[26 Aug 25 09:40 UTC] No.45024298[source]▶
I've been using OpenAPI for years with multiple versioning types (header based, content negotiation + media type based) and haven't had issues across Java, Typescript or Go with generating the right code for it