mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-02-04 18:21:47 +02:00
fresh build
This commit is contained in:
Sergey Konstantinov
parent
882accf563
commit
92a9dc4088
BIN
docs/API.en.epub
BIN
docs/API.en.epub
Binary file not shown.
@ -1935,7 +1935,11 @@ POST /v1/orders
|
||||
}
|
||||
</code></pre>
|
||||
<p>You may note that in this setup the error can't be resolved in one step: this situation must be elaborated over, and either order calculation parameters must be changed (discounts should not be counted against the minimal order sum), or a special type of error must be introduced.</p>
|
||||
<h5><a href="#chapter-11-paragraph-19" id="chapter-11-paragraph-19" class="anchor">19. No results is a result</a></h5>
|
||||
<h5><a href="#chapter-11-paragraph-19" id="chapter-11-paragraph-19" class="anchor">19. Stipulate future restrictions</a></h5>
|
||||
<p>With the API popularity growth, it will inevitably become necessary to introduce technical means of preventing illicit API usage, such as displaying captcha, setting honeypots, raising the ‘too many requests’ exceptions, installing anti-DDoS proxies, etc. All these things cannot be done if the corresponding errors and messages were not described in the docs from the very beginning.</p>
|
||||
<p>You are not obliged to actually generate those exceptions, but you might stipulate this possibility in the terms of service. For example, you might describe the <code>429 Too Many Requests</code> error or captcha redirect, but implement the functionality when it's actually needed.</p>
|
||||
<p>It is extremely important to leave a room for multi-factored authentication (such as TOTP, SMS, or 3D-secure-like technologies) in case it's possible to make payments through the API. In this case, it's a must have from the very beginning.</p>
|
||||
<h5><a href="#chapter-11-paragraph-20" id="chapter-11-paragraph-20" class="anchor">20. No results is a result</a></h5>
|
||||
<p>If a server processed a request correctly and no exceptional situation occurred — there must be no error. Regretfully, an antipattern is widespread — of throwing errors when zero results are found.</p>
|
||||
<p><strong>Bad</strong></p>
|
||||
<pre><code>POST /search
|
||||
@ -1962,7 +1966,7 @@ POST /v1/orders
|
||||
}
|
||||
</code></pre>
|
||||
<p>This rule might be reduced to: if an array is the result of the operation, then the emptiness of that array is not a mistake, but a correct response. (Of course, if an empty array is acceptable semantically; an empty array of coordinates is a mistake for sure.)</p>
|
||||
<h5><a href="#chapter-11-paragraph-20" id="chapter-11-paragraph-20" class="anchor">20. Localization and internationalization</a></h5>
|
||||
<h5><a href="#chapter-11-paragraph-21" id="chapter-11-paragraph-21" class="anchor">21. Localization and internationalization</a></h5>
|
||||
<p>All endpoints must accept language parameters (for example, in a form of the <code>Accept-Language</code> header), even if they are not being used currently.</p>
|
||||
<p>It is important to understand that the user's language and the user's jurisdiction are different things. Your API working cycle must always store the user's location. It might be stated either explicitly (requests contain geographical coordinates) or implicitly (initial location-bound request initiates session creation which stores the location), but no correct localization is possible in absence of location data. In most cases reducing the location to just a country code is enough.</p>
|
||||
<p>The thing is that lots of parameters potentially affecting data formats depend not on language, but on a user's location. To name a few: number formatting (integer and fractional part delimiter, digit groups delimiter), date formatting, the first day of the week, keyboard layout, measurement units system (which might be non-decimal!), etc. In some situations, you need to store two locations: user residence location and user ‘viewport’. For example, if a US citizen is planning a European trip, it's convenient to show prices in local currency, but measure distances in miles and feet.</p>
|
||||
|
||||
BIN
docs/API.en.pdf
BIN
docs/API.en.pdf
Binary file not shown.
BIN
docs/API.ru.epub
BIN
docs/API.ru.epub
Binary file not shown.
@ -1,9 +1,9 @@
|
||||
<!doctype html><html lang="ru_RU"><head>
|
||||
<meta charset="utf-8">
|
||||
<title>Сергей Константинов. The API</title>
|
||||
<title>Сергей Константинов. API</title>
|
||||
<meta name="author" content="Сергей Константинов">
|
||||
<meta name="description" content="Разработка API — особый навык: API является как мультипликатором ваших возможностей, так и мультипликатором ваших ошибок. Эта книга написана для того, чтобы поделиться опытом и изложить лучшие практики проектирования API. Книга состоит из двух больших разделов. В первом разделе мы поговорим о проектировании API на стадии разработки концепции — как грамотно выстроить архитектуру, от крупноблочного планирования до конечных интерфейсов. Второй раздел посвящён развитию существующих API с сохранением обратной совместимости">
|
||||
<meta property="og:title" content="Сергей Константинов. The API">
|
||||
<meta property="og:title" content="Сергей Константинов. API">
|
||||
<meta property="og:url" content="https://twirl.github.io/The-API-Book/index.ru.html">
|
||||
<meta property="og:type" content="article">
|
||||
<meta property="og:description" content="Разработка API — особый навык: API является как мультипликатором ваших возможностей, так и мультипликатором ваших ошибок. Эта книга написана для того, чтобы поделиться опытом и изложить лучшие практики проектирования API. Книга состоит из двух больших разделов. В первом разделе мы поговорим о проектировании API на стадии разработки концепции — как грамотно выстроить архитектуру, от крупноблочного планирования до конечных интерфейсов. Второй раздел посвящён развитию существующих API с сохранением обратной совместимости">
|
||||
@ -321,10 +321,10 @@ h1 {
|
||||
|
||||
<div class="cover">
|
||||
<h1>
|
||||
<span class="author">Сергей Константинов</span><br><span class="title">The API</span>
|
||||
<span class="author">Сергей Константинов</span><br><span class="title">API</span>
|
||||
</h1>
|
||||
</div><div class="page-break"></div><div class="annotation"><p>
|
||||
<strong>Сергей Константинов. The API.</strong><br>
|
||||
<strong>Сергей Константинов. API.</strong><br>
|
||||
<a target="_blank" href="mailto:yatwirl@gmail.com">yatwirl@gmail.com</a> · <a target="_blank" href="https://www.linkedin.com/in/twirl/">linkedin.com/in/twirl</a> · <a target="_blank" href="https://www.patreon.com/yatwirl">patreon.com/yatwirl</a></p>
|
||||
<p>«API-first» подход — одна из самых горячих горячих тем в разработке программного обеспечения в наше время. Многие компании начали понимать, что API выступает мультипликатором их возможностей — но также умножает и допущенные ошибки.</p>
|
||||
<p>Эта книга посвящена проектированию API: как правильно выстроить архитектуру, начиная с высокоуровневого планирования и заканчивая деталями реализации конкретных интерфейсов, и как развивать API, не нарушая обратную совместимость.</p>
|
||||
@ -1938,7 +1938,11 @@ POST /v1/orders
|
||||
}
|
||||
</code></pre>
|
||||
<p>Легко заметить, что в этом примере нет способа разрешить ошибку в один шаг — эту ситуацию требуется предусмотреть отдельно, и либо изменить параметры расчёта (минимальная сумма заказа не учитывает скидки), либо ввести специальную ошибку для такого кейса.</p>
|
||||
<h5><a href="#chapter-11-paragraph-19" id="chapter-11-paragraph-19" class="anchor">19. Отсутствие результата — тоже результат</a></h5>
|
||||
<h5><a href="#chapter-11-paragraph-19" id="chapter-11-paragraph-19" class="anchor">19. Предусмотрите ограничения</a></h5>
|
||||
<p>С ростом популярности API вам неизбежно придётся внедрять технические средства защиты от недобросовестного использования — такие, как показ капчи, расстановка приманок-honeypot-ов, возврат ошибок вида «слишком много запросов», постановка прокси-защиты от DDoS перед эндпойнтами и так далее. Всё это невозможно сделать, если вы не предусмотрели такой возможности изначально, а именно — не ввели соответствующей номенклатуры ошибок и предупреждений.</p>
|
||||
<p>Вы не обязаны с самого начала такие ошибки действительно генерировать — но вы можете предусмотреть их на будущее. Например, вы можете описать ошибку <code>429 Too Many Requests</code> или редирект на показ капчи, но не имплементировать возврат таких ответов, пока не возникнет такая необходимость.</p>
|
||||
<p>Отдельно необходимо уточнить, что в тех случаях, когда через API можно совершать платежи, ввод дополнительных факторов аутентификации пользователя (через TOTP, SMS или технологии типа 3D-Secure) должен быть предусмотрен обязательно.</p>
|
||||
<h5><a href="#chapter-11-paragraph-20" id="chapter-11-paragraph-20" class="anchor">20. Отсутствие результата — тоже результат</a></h5>
|
||||
<p>Если сервер корректно обработал вопрос и никакой внештатной ситуации не возникло — следовательно, это не ошибка. К сожалению, весьма распространён антипаттерн, когда отсутствие результата считается ошибкой.</p>
|
||||
<p><strong>Плохо</strong></p>
|
||||
<pre><code>POST /search
|
||||
@ -1965,7 +1969,7 @@ POST /v1/orders
|
||||
}
|
||||
</code></pre>
|
||||
<p>Это правило вообще можно упростить до следующего: если результатом операции является массив данных, то пустота этого массива — не ошибка, а штатный ответ. (Если, конечно, он допустим по смыслу; пустой массив координат, например, является ошибкой.)</p>
|
||||
<h5><a href="#chapter-11-paragraph-20" id="chapter-11-paragraph-20" class="anchor">20. Локализация и интернационализация</a></h5>
|
||||
<h5><a href="#chapter-11-paragraph-21" id="chapter-11-paragraph-21" class="anchor">21. Локализация и интернационализация</a></h5>
|
||||
<p>Все эндпойнты должны принимать на вход языковые параметры (например, в виде заголовка <code>Accept-Language</code>), даже если на текущем этапе нужды в локализации нет.</p>
|
||||
<p>Важно понимать, что язык пользователя и юрисдикция, в которой пользователь находится — разные вещи. Цикл работы вашего API всегда должен хранить локацию пользователя. Либо она задаётся явно (в запросе указываются географические координаты), либо неявно (первый запрос с географическими координатами инициировал создание сессии, в которой сохранена локация) — но без локации корректная локализация невозможна. В большинстве случаев локацию допустимо редуцировать до кода страны.</p>
|
||||
<p>Дело в том, что множество параметров, потенциально влияющих на работу API, зависят не от языка, а именно от расположения пользователя. В частности, правила форматирования чисел (разделители целой и дробной частей, разделители разрядов) и дат, первый день недели, раскладка клавиатуры, система единиц измерения (которая к тому же может оказаться не десятичной!) и так далее. В некоторых ситуациях необходимо хранить две локации: та, в которой пользователь находится, и та, которую пользователь сейчас просматривает. Например, если пользователь из США планирует туристическую поездку в Европу, то цены ему желательно показывать в местной валюте, но отформатированными согласно правилам американского письма.</p>
|
||||
|
||||
BIN
docs/API.ru.pdf
BIN
docs/API.ru.pdf
Binary file not shown.
@ -6,7 +6,7 @@
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<link rel="icon" type="image/jpg" href="assets/favicon.jpg" />
|
||||
<title>
|
||||
Сергей Константинов. The API
|
||||
Сергей Константинов. API
|
||||
</title>
|
||||
<meta
|
||||
name="description"
|
||||
@ -15,7 +15,7 @@
|
||||
<meta property="og:type" content="article" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Сергей Константинов. The API"
|
||||
content="Сергей Константинов. API"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
@ -159,9 +159,9 @@
|
||||
<nav>
|
||||
<img
|
||||
src="assets/header.jpg"
|
||||
alt="Сергей Константинов. The API"
|
||||
alt="Сергей Константинов. API"
|
||||
/><br />
|
||||
<h1>Сергей Константинов<br/><span class="title">The API</span></h1>
|
||||
<h1>Сергей Константинов<br/><span class="title">API</span></h1>
|
||||
<h2>Бесплатная электронная книга</h2>
|
||||
<br />Подпишитесь на обновления на <a class="habr" href="https://habr.com/ru/users/forgotten/posts/">Хабре</a>
|
||||
|
||||
|
||||
@ -1039,6 +1039,4 @@ Sometimes explicit location passing is not enough since there are lots of territ
|
||||
|
||||
Worth mentioning is that the `localized_` prefix in the example is used to differentiate messages to users from messages to developers. A concept like that must be, of course, explicitly stated in your API docs.
|
||||
|
||||
And one more thing: all strings must be UTF-8, no exclusions.
|
||||
|
||||
#####
|
||||
And one more thing: all strings must be UTF-8, no exclusions.
|
||||
@ -1,5 +1,5 @@
|
||||
{
|
||||
"title": "The API",
|
||||
"title": "API",
|
||||
"author": "Сергей Константинов",
|
||||
"chapter": "Глава",
|
||||
"toc": "Содержание",
|
||||
@ -25,7 +25,7 @@
|
||||
},
|
||||
"sourceCodeAt": "Исходный код доступен на",
|
||||
"frontPage": {
|
||||
"title": "The API",
|
||||
"title": "API",
|
||||
"pageTitle": "Титульный лист",
|
||||
"contents": [
|
||||
"<p>«API-first» подход — одна из самых горячих горячих тем в разработке программного обеспечения в наше время. Многие компании начали понимать, что API выступает мультипликатором их возможностей — но также умножает и допущенные ошибки.</p>",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user