books/The-API-Book
1
0
Fork 0
mirror of https://github.com/twirl/The-API-Book.git synced 2025-08-10 21:51:42 +02:00
Code Issues Releases Activity

proofreading

Browse Source
This commit is contained in:
Sergey Konstantinov
2023-04-30 23:26:13 +03:00
parent a57210bfbe
commit 92458ae70c
2 changed files with 14 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/en/clean-copy/02-Section I. The API Design/01.md
View File

@@ -10,4 +10,4 @@ This four-step algorithm actually builds an API from top to bottom, from common
It might seem that the most useful pieces of advice are given in the last chapter, but that's not true. The cost of a mistake made at certain levels differs. Fixing the naming is simple; revising the wrong understanding of what the API stands for is practically impossible.
**NB**. Here and throughout we will illustrate the API design concepts using a hypothetical example of an API allowing for ordering a cup of coffee in city cafes. Just in case: this example is totally synthetic. If we were to design such an API in the real world, it would probably have very little in common with our fictional example.
**NB**. Here and throughout we will illustrate the API design concepts using a hypothetical example of an API that allows ordering a cup of coffee in city cafes. Just in case: this example is totally synthetic. If we were to design such an API in the real world, it would probably have very little in common with our fictional example.

26
src/en/clean-copy/02-Section I. The API Design/02.md
View File

@@ -1,6 +1,6 @@
### [Defining an Application Field][api-design-defining-field]
The key question you should ask yourself before we start developing any software product, including an API, is: what problem do we solve? It should be asked four times, each time putting an emphasis on another word.
The key question you should ask yourself before starting to develop any software product, including an API, is: what problem do we solve? It should be asked four times, each time putting emphasis on a different word.
1. *What* problem do we solve? Could we clearly outline the situation in which our hypothetical API is needed by developers?
@@ -12,7 +12,7 @@ The key question you should ask yourself before we start developing any software
So, let's imagine that we are going to develop an API for automated coffee ordering in city cafes, and let's apply the key question to it.
1. Why would someone need an API to make a coffee? Why ordering a coffee via “human-to-human” or “human-to-machine” interfaces is inconvenient, why have a “machine-to-machine” interface?
1. Why would someone need an API to make coffee? Why is ordering coffee via “human-to-human” or “human-to-machine” interfaces inconvenient? Why have a “machine-to-machine” interface?
* Possibly, we're solving awareness and selection problems? To provide humans with full knowledge of what options they have right now and right here.
* Possibly, we're optimizing waiting times? To save the time people waste while waiting for their beverages.
@@ -22,30 +22,30 @@ So, let's imagine that we are going to develop an API for automated coffee order
Here and throughout we assume, to make our example more complex and bizarre, that we are optimizing all three factors.
2. Do the problems we outlined really exist? Do we really observe unequal coffee-machines utilization in the mornings? Do people really suffer from the inability to find nearby a toffee nut latte they long for? Do they really care about the minutes they spend in lines?
2. Do the problems we outlined really exist? Do we really observe unequal coffee-machine utilization in the mornings? Do people really suffer from the inability to find nearby a toffee nut latte they long for? Do they really care about the minutes they spend in lines?
3. Do we actually have resources to solve the problem? Do we have access to a sufficient number of coffee machines and users to ensure the system's efficiency?
4. Finally, will we really solve a problem? How we're going to quantify the impact our API makes?
4. Finally, will we really solve a problem? How are we going to quantify the impact our API makes?
In general, there are no simple answers to those questions. Ideally, you should start the work having all the relevant metrics measured: how much time is wasted exactly, and what numbers we're going to achieve providing we have such coffee machines density. Let us also stress that in the real world obtaining these numbers is only possible if you're entering a stable market. If you try to create something new, your only option is to rely on your intuition.
In general, there are no simple answers to those questions. Ideally, you should start the work with all the relevant metrics measured: how much time is wasted exactly, and what numbers will we achieve providing we have such a coffee machine density. Let us also stress that in the real world obtaining these numbers is only possible if you're entering a stable market. If you try to create something new, your only option is to rely on your intuition.
#### Why an API?
Since our book is dedicated not to software development per se, but to developing APIs, we should look at all those questions from a different angle: why does solving those problems specifically require an API, not simply a specialized software application? In terms of our fictional example, we should ask ourselves: why provide a service to developers, allowing for brewing coffee to end users, instead of just making an app?
Since our book is dedicated not to software development per se, but to developing APIs, we should look at all those questions from a different angle: why does solving those problems specifically require an API, not simply a specialized software application? In terms of our fictional example, we should ask ourselves: why provide a service to developers that allows for brewing coffee for end users instead of just making an app?
In other words, there must be a solid reason to split two software development domains: there are vendors that provide APIs, and there are vendors that develop services for end users. Their interests are somehow different to such an extent that coupling these two roles in one entity is undesirable. We will talk about the motivation to specifically provide APIs instead of apps (or as an addition to an app) in more detail in Section III.
We should also note that you should try making an API when, and only when, your answer to question (3) is "because that's our area of expertise". Developing APIs is a sort of meta-engineering: you're writing some software to allow other vendors to develop software to solve users' problems. You must possess expertise in both domains (APIs and user products) to design your API well.
We should also note that you should try making an API when, and only when, your answer to question (3) is “because that's our area of expertise.” Developing APIs is a sort of meta-engineering: you're writing some software to allow other vendors to develop software to solve users' problems. You must possess expertise in both domains (APIs and user products) to design your API well.
As for our speculative example, let us imagine that in the nearby future, some tectonic shift happened within the coffee brewing market. Two distinct player groups took shape: some companies provide “hardware,” i.e., coffee machines; other companies have access to customer auditory. Something like the modern-day flights market looks like: there are air companies, which actually transport passengers; and there are trip planning services where users are choosing between trip variants the system generates for them. We're aggregating hardware access to allow app vendors for ordering freshly brewed coffee.
As for our speculative example, let us imagine that in the nearby future, some tectonic shift happened within the coffee brewing market. Two distinct player groups took shape: some companies provide “hardware,” i.e., coffee machines; other companies have access to customer audiences. Something like the modern-day flights market looks like: there are air companies that actually transport passengers, and there are trip planning services where users choose between trip options the system generates for them. We're aggregating hardware access to allow app vendors to order freshly brewed coffee.
#### What and How
After finishing all these theoretical exercises, we should proceed right to designing and developing the API, having a decent understanding of two things:
* *what* we're doing, exactly;
* *how* we're doing it, exactly.
After finishing all these theoretical exercises, we should proceed directly to designing and developing the API, having a decent understanding of two things:
* *what* we're doing exactly
* *how* we're doing it exactly.
In our coffee case, we are:
* providing an API to services with a larger audience, so their users may order a cup of coffee in the most efficient and convenient manner;
* abstracting access to coffee machines' “hardware” and developing generalized software methods to select a beverage kind and some location to make an order.
* providing an API to services with a larger audience so that their users may order a cup of coffee in the most efficient and convenient manner
* abstracting access to coffee machines' “hardware” and developing generalized software methods to select a beverage kind and a location to make an order.