The Design of Everyday APIs (2022) | Hacker News Reader

The Design of Everyday APIs (2022)

roguelynn.com

166 pointsresiros17 comments

Not to jump off topic, but my takeaway from Norman's "The Design of Everyday Things" was that design is of process of compromises. Could be time, could be budget, could be other factors within the company, etc. But there are almost always unseen forces the public isn't aware of that impacts the design they do see.

I would presume APIs are no different. There is no objective and absolute perfect API. Instead there are always tradeoffs, always compromises.

I've been contemplating something along these lines for a bit: Step one is to understand the tradeoff space. Step two (which is sometimes much more difficult) is picking where in the tradeoff space makes sense for the business, but now and into the future.

> but now and into the future.

That's tough. The context is always changing. The future looks different every week or two. Worth considering but it's also easy to go down the rabbit hole of over anticipating, over planning, etc.

Be wise. Be thorough. But be aware you'll be wrong often (when it comes to predicting the future).

The best predictors don’t scout all roads, they instead avoid decisions that cut them off.

We still have a legacy of bad design we were chasing in the 00’s and well into the 10’s of trying to future proof things when what we should have been doing was hedging by putting off decisions we cannot change as long as we possibly can: the Last Responsible Moment is too often conflated with YAGNI - things like building infrastructure “you don’t need yet” (need is open to interpretation and a clogged roadmap full of long runways often means that targets of opportunity should be pursued when the trail is hot, not when the “time is right”. There is never time, only opportunity). When instead I think it is more about jumping off ledges with no trail back. I cannot reverse this decision, so I should avoid it as long as I reasonably can.

Stall until there is more information, until your tools are better, until the requirements are clear, until workarounds and interim solutions do not suffice and you must commit.

Stall, study, scaffold.

> There is never time, only opportunity

Brilliant. I agree with everything you said. Present me has no idea what future me needs. Let future me decide. Keep things simple and flexible as long as possible.

Absolutely. Recently at $JOB, during discussions about designing a new system, I recalled the quote by Thomas Sowell: "There are no solutions, only trade-offs."

Eames said "Design depends largely on constraints".

https://www.hermanmiller.com/stories/why-magazine/design-q-a...

Regarding compromise, he said:

> Have you been forced to accept compromises?

> > I don’t remember ever being forced to accept compromises, but I have willingly accepted constraints.

I think the book sets out to explain 2 things, and does that really well:

1. Why do everyday things end up being designed the way they are 2. What makes one thing designed well and another not?

Normann definitely goes out of his way to say that some things are poorly designed and other are not.

One of my favourite bits is on stove tops. He argues why basically every stovetops knob-layout is wrong and then goes on to explain why we end up with a "wrong" layout: It is because stovetops are designed to be sold in the showroom, more than they are designed to be used in the kitchen. It looks nice to have the knobs in a row (the book is from before touch controls) and that's why they are in a row and not in a square configuration.

I don't think the takeaway here is "it's a compromise, and it is what it is", I think the point Norman wants to make is more along the lines of "This is why we can't have nice things".

That's sort of true but also used as an excuse for crappy design/execution.

To nitpick: __repr__() is meant to produce a string s.t. if read from (by the Python parser) and subsequently evaluated, will create an object as similar as possible to "self".

OP kind of messed that part up.

On other counts: I don't know... a lot of this seems true, but also very simple, to the point that I don't know if it needs a special mention. In other words, maybe, to get a better insight into how to make better API one needs to keep looking for "deeper" answers.

Also, a lot of practices and techniques this presentation argues against have their merits (eg. having explicit close() method is right out of "Zen of Python" which tells to use explicit over implicit).

Perhaps, a better analysis would try to defend the given approach in the light of the justification for the opposite, or, at least, try to assign weights to different approaches (eg. "if explicit code makes user code more prone to error, then implicit should be preferred").

recording: https://www.youtube.com/watch?v=0qYDmm1O7hc

link to YouTube video with better audio: https://www.youtube.com/watch?v=bVoM2WLt6Hk

Slightly API related rant:

I just wanted to get my free/busy info from office 365. I wanted to control a "do not disturb" light without using a phone app. There doesn't seem to be any straightforward method to "generate a token, save it in Bruno or Postman etc, then POST to a specific endpoint". The docs I saw talk about registering an app, and all sorts of heavyweight stuff in Azure.

Why can't I just call some URL, or add a webhook somewhere and be done with it?

You can sign into Graph Explorer and get an access token there:

https://developer.microsoft.com/en-us/graph/graph-explorer

No clue how long it lasts.

Oh, that is cool!

But corporate IT has apparently blocked being able to use graph-explorer.

Thank you anyway! :)

Guess it’s time to scrape your calendar from web?

You can also use the outlook COM API and extract the data from the running outlook instance [1]. See [2] for a python example that extracts a '.ics' file.

[1] https://learn.microsoft.com/en-us/office/vba/api/outlook.cal...

[2] https://github.com/TomSmeets/export-outlook-to-ics/blob/mast...

Reply on news.ycombinator.com