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 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 developers of the interface.
• The girls with their shop assistant interface forms multiple subsystems 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)