A, P, I - put together the words
Tags: api
Published: 2019-07-04 13:08:22

_Yet another introduction to API_

_ORIGINAL: https://write.as/voanhcuoc/a-p-i-put-together-the-words_

# Context

For now, I'm mentoring some of my friends on how to develop software. They are smart ones, they know how to code but haven't had any exposure at all to the software development process. The first rock I stumble upon was to explain to them **what, why and how to do API** (Application Programming Interface, _in its **broadest meaning**_).

For god sake, I'm a lazy person so I just want to search the Internet for some blog posts or lectures, that usually will explain it better than me. But no, there's no such single article that presents my understandings. [The Wikipedia post](https://en.wikipedia.org/wiki/Application_programming_interface) is good but it's rendered unlearnable by newbie. Finally, I feel the urge to write a post myself!

# API - an overloaded term

_P/S: The best way to learn from this article, is to first read it from top down, then read it again from bottom up, per the unit of each section._

## Web API

Thanks to the rise of cloud computing and microservice architecture, the meaning of word _API_ in common sense has nearly been superseded by _Web API (i.e. API exposed through a network, mostly Internet)_.

> When business people refer to _API_, they always mean _Web API_.

This one, although should be put far down the learning path, always appear in the first Google results.

## SDK (Software Development Kit)

_API_ is not _SDK_ and vice versa. They are different concepts anyway.

_SDK_ is a term under the umbrella of technology. Technology provider may give you an _SDK_ so you can build software that utilizes or applies their technology. (e.g. You can use _Kinect SDK for Windows_ to apply _Kinect technology_)

An _SDK_ is a toolkit. The toolkit comprises of tools. And there's mostly always an _API_ inside it. **_API_ is a tool** in terms of _SDK_.

> _SDK_ usually consists of **at least one _API_**.
> _API_ may be provided **alone** or **within an _SDK_**.

What's crucial here, is the new understanding of _API_ arising from the view of _API_ as a tool.

> When _application software developers_ refer to _API_, they mostly mean the _API_ as a tool.

To be clear _application software developers_ is who design or implement User Interface, not who design or implement _API_. They only make use of _API_s. The understanding of _API as a tool_ is enough for them...

## Programming Interface - the P and I

... but not for _API developers_, who _create the API_.

User Interface and Programming Interface are vastly different. Users are living people that can adjust their behavior to adapt the interface, while a computer is a mindless machine which hardly does that (only if consciously instructed to do so with huge effort).

_Application developer_ can utilize the _common sense of people_ to make User Interface. _API developers_ only have some _community conventions_ which is served only as a reference and cannot be relied upon.

For example:

* The red close button in the corner of a window can be used to quit the entire program, or just minimize it - based on which program it is. A user may be confused if the behavior is not what they expect in the first place, but he can quickly learn about it later on.

* In science community using Python, there's a convention that matrices is presented by `numpy.ndarray` data structure, most of the time. Which is great, but you can't rely on it, you must confirm it by looking at official information sources before using `numpy.ndarray` API on these matrices. If you assume that and start coding, then your program may break and you'll be surprised that matrices are presented by a different data structure from a different library.

As you will notice, the term _programming interface_ (without _application_) is rarely used outside. People say _ey - pee - eye_ everywhere.

It's pretty reasonable, the purpose of every _programming interface_ ever created is **to apply** a piece of software. If not that then what? From my experience, I just can't point out any case that _programming interface_ created not for applying the software.

So, _API_ ≈ _programming interface_

> _API developer_ view software they develop as a system, and API is the _interface_ that system expose to other software programs.

## Interface - the I

Let build a conceptual model of _interface_ in general.

_Interface_ define how an _individual system_ interact with the outside world. At the analysis level, _interface_ is everything about the system we take into account, so we can say:

> The _interface_ define the _system_.

For example, every day you walk into a convenience store (such as Circle K) to buy something, here's a step-by-step description of what happens:

1. At first, the _shop assistant_ greet you.
2. You ask her for some items, she points you to where it is.
3. You come there and choose what you'd like to buy.
4. You take it to her, she tells you its price.
5. You give her money, then take the item and get out of the store.

Day to day, you come to the store and meet different shop assistant: yesterday is Karen, today is Sarah, tomorrow is Helen... But you and she always go through the same process as I describe above. In summary:

1. Karen, Sarah or Helen, ... implement _shop assistant interface_ (as described above).
2. You interact with a _shop assistant_ to buy items.

All these girls are _the same_ for you as a customer. As analysis level,  are _the same_ system to you. 

> That system is defined by the _interface_ above, hence named _shop assistant_.

Let clarify the roles here:

* You are the **user** of the _interface_.
* The girls and the store manager work together to provide the _interface_ available at the store. They're **developer**s of the _interface_.
* The girls with their _shop assistant interface_ forms multiple **subsystem**s of the larger **system** (the store).
* They're exchangeable cause the same _interface_. So without the presence of each girl every day. The store is still able to _expose_ the _shop assistant interface_, every day.

> An interface may be implemented by multiple _system_. (Each one called an _implementation_ of that interface)

_But there's something wrong! The girls are human and they're different ..._

Yep, of course. One day you feel that Karen is so cute and gonna flirt with her. After a while, she agrees to have a date with you. You both have lunch, take a walk, talk about hobbies and family, then have sex... Now Karen is different from Sarah and Helen.

> Karen exposes _lover interface_ to you.

But she is still the same as other girls, to me. And the same to you as a customer too: No matter you both are lovers, you still can go to that store and ask Karen for information of items, she still implement _shop assistant interface_ to you.

> A _system_ may expose multiple _interface_s.

An interface is like a piece of water. You take a piece of water and pour it into 2 cups, one for you and one for Karen. Bump! You have 2 pieces of water, cause you've named them. Karen is defined by interface she exposes to the world. If you split her interface into multiple interfaces as I do above, then we can think that she exposes multiple interfaces: _shop assistant_, _lover_, _friend_, _child_, ...

To be continued ...

_TODO write about performance as the quality of implementations (in ideal situation, implementations conforms 100% to the interface)_