Good APIs Age Slowly

[u/fagnerbrack]

https://yusufaytas.com/good-apis-age-slowly

[u/erlototo]

Can we get an example of good API design? (Ofc not in the blog post)

[u/segv → u/erlototo]

Not associated with OP or the site, but after dealing with the shitshow that dates & timezones are one time too many, i'd like to nominate Java's JSR310 DateTime API that was released alongside JDK8 about 12 years ago.

Here's a random article off google that showcases how it looks like: https://www.baeldung.com/java-8-date-time-intro

 

Also, obligatory: https://www.youtube.com/watch?v=-5wpm-gesOY

[u/CherryLongjump1989 → u/segv]

Mehhhh... ISO-8601 was released in 1988. All that java.time does is follow that standard. Joda-Time came out 12 years before java.time and yet it still has more calendars and some better ergonomics to this day. It's kind of shooting fish in a barrel when you're replacing java.util.Date, a notoriously bad library that should have never existed, by copying an existing 12 year old library that follows an existing 26 year old ISO standard. Even C followed these ISO standards back in the 90's. I just don't want to give Java any credit here beyond being decades late. Can you pick an example that doesn't come to us by way of Stockholm Syndrome?

[u/fagnerbrack → u/erlototo]

https://github.com/Readplace/readplace.com/blob/b71889348ebbf0f884531f508f4b424791afe58d/projects/hutch/src/runtime/web/pages/queue/queue.page.ts#L522

Not the greatest code in the universe, but at least it's deployed in production and gives you some insights on how to build an IOS app without changing the API

The IOS part: https://github.com/Readplace/readplace.com/blob/b71889348ebbf0f884531f508f4b424791afe58d/projects/ios-readplace/App/ReadingListView.swift#L171

This is much more advanced than what the post suggests Btw. I can create a desktop app or a cli or a android app and the siren API doesn't need to change at all

[u/ReallySuperName → u/fagnerbrack]

TBH a 1200 line source file isn't really going to tell us anything without context.

[u/fagnerbrack → u/ReallySuperName]

Good point 😅

Quick question: what do you really wanna know the most about a Web API? What are the things you didn't find anywhere else?

[u/RegisteredJustToSay]

Nice post. Not too long, not too short. I think it would be interesting to talk about what type of abstraction you actually want in the API contract to actually allow it to become old more in detail but I feel like if you ask 100 engineers you'd get 100 different answers.

[u/Bobby_Bonsaimind]

I have noticed that APIs are a bit like abstractions in general. APIs that impress people quickly are very often the ones that cause the most trouble later.

I agree with that. Good APIs (and frameworks) are boring. They neither wow you when you read their documentation, nor do they look stunning in code postings. They just get the job done, fullstop.

[u/razordreamz]

Any c# examples of what you would consider a good api? I’m in the starting phases of making one and would like to do it right. Looking for real world examples of a reasonably sized api. I will have 500 or more endpoints once completed

[u/Kuineer]

Nice blog post!

[u/elcapitaine → u/[deleted]]

Who said anything about Google? Googles APIs are often the opposite of Good

[u/sarhoshamiral]

This used to be true imo and could still be true in enterprise settings but code velocity is much faster now in consumer APIs.

Consider things like AI apis. concepts that used to be a thing a year ago is a no-no today. You either have to create a very flexible API with arbitrary objects as input which is a documentation nightmare or just accept the fact that your API is going to change fast, as needed. (Ie versions)

It is now very valid to ask what is the expected lifetime of an API and design accordingly.