How APIs Work – An Analogy for Dummies | Hacker News Reader

How APIs Work – An Analogy for Dummies

medium.com

63 pointskiyanwang9 comments

This is a good read and explains APIs in detail.

Can someone do a similar analogy for micro-services? Quite a lot of times I struggle to explain people there are two different things.

Everything I know about microservices stems from 2 quotes. One is an excerpt of _The Fifth Elephant_ by Terry Pratchett:

  "This, milord, is my family's axe. We have owned it for almost nine hundred
  years, see. Of course, sometimes it needed a new blade. And sometimes it has
  required a new handle, new designs on the metalwork, a little refreshing
  of the ornamentation... but is this not the nine hundred-year-old axe of my
  family? And because it has changed gently over time, it is still a pretty
  good axe, y'know. Pretty good."

And the other is a tweet from Honest Status Pages (@honest_update)

  We replaced our monolith with micro services so that every outage could be more like a murder mystery.

atm

I had a similar case where I had to explain APIs to a broad audience of people starting with React.js. So I took the approach to take them on a journey how I learned about APIs in their different contexts and how they can empower one to build applications [0]. Maybe it is interesting for someone of you too.

- [0] https://www.robinwieruch.de/what-is-an-api-javascript/

Think of a restaurant: you use the menu to order things from the kitchen. If an item appears on the menu but is not actually available from the kitchen, you would be pissed off.

The menu is the API, what comes out of the kitchen is the implementation.

The menu is part of the API, the waiter is another part (a part which may tell you that unfortunately that particular dish isn't available anymore today)

APIs don't work. API is the passive part of a library.

Edit: would the downvoters explain to me why stealing an already well-established term API to mean a largely unrelated concept of a service (RPC service) is a good idea?

From the HN guidelines:

Please don't comment about the voting on comments. It never does any good, and it makes boring reading.

There's just such an overwhelming amount of content in that article to show that the author didn't fall into the trap you're accusing him of.

A few extracts:

> a way to implement an API

> …[APIs are] a set of subroutine definitions, protocols, and tools for building application software. In general terms, it's a set of clearly defined methods of communication between various software components.

> Similarly, if we abstract away the implementation details of operations

> Components can be swapped out and replaced as long as they follow the same protocol

Reply on news.ycombinator.com