style fix

docs/API.ru.html

@@ -18,7 +18,10 @@
 
 @media print {
     h1 {
-        margin: 3.5in 0 4in 0;
+        margin: 4.5in 0 5.2in 0;
+    }
+    body {
+        font-size: 20pt;
     }
 }
 
@@ -29,13 +32,15 @@
 
 code, pre {
     font-family: Inconsolata, sans-serif;
-    font-size: 12pt;
+}
+
+code {
     white-space: nowrap;
 }
 
 pre {
-    margin: 12pt 0;
-    padding: 12pt;
+    margin: 1em 0;
+    padding: 1em;
     border-radius: .25em;
     border-top: 1px solid rgba(0,0,0,.45);
     border-left: 1px solid rgba(0,0,0,.45);
@@ -43,6 +48,10 @@ pre {
     page-break-inside: avoid;
 }
 
+pre code {
+    white-space: pre;
+}
+
 .page-break {
     page-break-after: always;
 }
@@ -55,22 +64,23 @@ h1, h2, h3, h4, h5 {
     text-align: left;
     font-family: 'PT Sans';
     font-weight: bold;
+    page-break-after: avoid;
 }
 
 h1 {
-    font-size: 28pt;
+    font-size: 200%;
 }
 
 h2 {
-    font-size: 24pt;
+    font-size: 160%;
 }
 
 h3 {
-    font-size: 20pt;
+    font-size: 140%;
 }
 
 h4, h5 {
-    font-size: 16pt;
+    font-size: 120%;
 }
 
 @page {
@@ -227,7 +237,9 @@ POST /v1/bucket/{id}/some-resource
 <pre><code>  // возвращает рецепт лунго
   GET /v1/recipes/lungo
 </code></pre>
-<pre><code>  // размещает на указанной кофе-машине заказ на приготовление лунго и возвращает идентификатор заказа
+<pre><code>  // размещает на указанной кофе-машине
+  // заказ на приготовление лунго
+  // и возвращает идентификатор заказа
   POST /v1/coffee-machines/orders?machine_id={id}
   {
     "recipe": "lungo"
@@ -599,17 +611,16 @@ GET /sensors
 <p>Важно понимать, что вы вольны вводить свои собственные конвенции. Например, в некоторых фреймворках сознательно отказываются от парных методов <code>set_entity</code> / <code>get_entity</code> в пользу одного метода <code>entity</code> с опциональным параметром. Важно только проявить последовательность в её применении — если такая конвенция вводится, то абсолютно все методы API должны иметь подобную полиморфную сигнатуру, или по крайней мере должен существовать принцип именования, отличающий такие комбинированные методы от обычных вызовов.</p>
 <h4 id="1">1. Явное лучше неявного</h4>
 <p>Из названия любой сущности должно быть очевидно, что она делает и к каким сайд-эффектам может привести её использование.</p>
-<ul>
-<li><p><strong>Плохо</strong>:  </p>
+<p><strong>Плохо</strong>:  </p>
 <pre><code>// Отменяет заказ
 GET /orders/cancellation
 </code></pre>
-<p>Неочевидно, что достаточно просто обращения к сущности <code>cancellation</code> (что это?), тем более немодифицирующим методом <code>GET</code>, чтобы отменить заказ;  </p>
+<p>Неочевидно, что достаточно просто обращения к сущности <code>cancellation</code> (что это?), тем более немодифицирующим методом <code>GET</code>, чтобы отменить заказ.</p>
 <p><strong>Хорошо</strong>:  </p>
 <pre><code>// Отменяет заказ
 POST /orders/cancel
-</code></pre></li>
-<li><p><strong>Плохо</strong>:</p>
+</code></pre>
+<p><strong>Плохо</strong>:</p>
 <pre><code>// Возвращает агрегированную статистику заказов за всё время
 GET /orders/statistics
 </code></pre>
@@ -618,81 +629,65 @@ GET /orders/statistics
 <pre><code>// Возвращает агрегированную статистику заказов за указанный период
 POST /v1/orders/statistics/aggregate
 { "start_date", "end_date" }
-</code></pre></li>
-</ul>
+</code></pre>
 <p><strong>Стремитесь к тому, чтобы из сигнатуры функции было абсолютно ясно, что она делает, что принимает на вход и что возвращает</strong>. Вообще, при прочтении кода, работающего с вашим API, должно быть сразу понятно, что, собственно, он делает — без подглядывания в документацию.</p>
 <p>Два важных следствия:</p>
 <p><strong>1.1.</strong> Если операция модифицирующая, это должно быть очевидно из сигнатуры. В частности, не может быть модифицирующих операций за <code>GET</code>.</p>
 <p><strong>1.2.</strong> Если в номенклатуре вашего API есть как синхронные операции, так и асинхронные, то (а)синхронность должна быть очевидна из сигнатур, <strong>либо</strong> должна существовать конвенция именования, позволяющая отличать синхронные операции от асинхронных.</p>
 <h4 id="2">2. Использованные стандарты указывайте явно</h4>
 <p>К сожалению, человечество не в состоянии договориться о таких простейших вещах, как «с какого дня начинается неделя», что уж говорить о каких-то более сложных стандартах.</p>
-<p>Поэтому <em>всегда</em> указывайте, по какому конкретно стандарту вы отдаёте те или иные величины. Исключения возможны только там, где вы на 100% уверены, что в мире существует только один стандарт для этой сущности, и всё население земного шара о нём в курсе:</p>
-<ul>
-<li><strong>плохо</strong>: <code>"date":"11/12/2020"</code> — стандартов записи дат существует огромное количество, плюс из этой записи невозможно даже понять, что здесь число, а что месяц;<br />
-<strong>хорошо</strong>: <code>"iso_date":"2020-11-12"</code>.</li>
-<li><strong>плохо</strong>: <code>"duration":5000</code> — пять тысяч чего?<br />
-<strong>хорошо</strong>:<br />
-<code>"duration_ms":5000</code><br />
-либо<br />
-<code>"duration":"5000ms"</code><br />
-либо<br />
-<code>"duration":{"unit":"ms","value":5000}</code>.</li>
-</ul>
+<p>Поэтому <em>всегда</em> указывайте, по какому конкретно стандарту вы отдаёте те или иные величины. Исключения возможны только там, где вы на 100% уверены, что в мире существует только один стандарт для этой сущности, и всё население земного шара о нём в курсе.</p>
+<p><strong>Плохо</strong>: <code>"date":"11/12/2020"</code> — стандартов записи дат существует огромное количество, плюс из этой записи невозможно даже понять, что здесь число, а что месяц.</p>
+<p><strong>Хорошо</strong>: <code>"iso_date":"2020-11-12"</code>.</p>
+<p><strong>Плохо</strong>: <code>"duration":5000</code> — пять тысяч чего?</p>
+<p><strong>Хорошо</strong>:<br />
+    <code>"duration_ms":5000</code><br />
+    либо<br />
+    <code>"duration":"5000ms"</code><br />
+    либо<br />
+    <code>"duration":{"unit":"ms","value":5000}</code>.</p>
 <p>Отдельное следствие из этого правила — денежные величины <em>всегда</em> должны сопровождаться указанием кода валюты.</p>
 <p>Также следует отметить, что в некоторых областях ситуация со стандартами настолько плоха, что как ни сделай — кто-то останется недовольным. Классический пример такого рода — порядок географических координат ("широта-долгота" против "долгота-широта"). Здесь, увы, есть только один работающий метод борьбы с фрустрацией — «блокнот душевного спокойствия», который будет описан в разделе II.</p>
 <h4 id="3">3. Сохраняйте точность дробных чисел</h4>
 <p>Там, где это позволено протоколом, дробные числа с фиксированной запятой — такие, как денежные суммы, например — должны передаваться в виде специально предназначенных для этого объектов, например, Decimal или аналогичных.</p>
 <p>Если в протоколе нет Decimal-типов (в частности, в JSON нет чисел с фиксированной запятой), следует либо привести к целому (путём домножения на указанный множитель), либо использовать строковый тип.</p>
 <h4 id="4">4. Сущности должны именоваться конкретно</h4>
-<p>Избегайте слов-«амёб» без определённой семантики, таких как get, apply, make. Сущности должны именоваться конкретно:</p>
-<ul>
-<li><strong>плохо</strong>: <code>user.get()</code> — неочевидно, что конкретно будет возвращено;<br />
-<strong>хорошо</strong>: <code>user.get_id()</code>.</li>
-</ul>
+<p>Избегайте слов-«амёб» без определённой семантики, таких как get, apply, make. Сущности должны именоваться конкретно.</p>
+<p><strong>Плохо</strong>: <code>user.get()</code> — неочевидно, что конкретно будет возвращено.</p>
+<p><strong>Хорошо</strong>: <code>user.get_id()</code>.</p>
 <h4 id="5">5. Не экономьте буквы</h4>
 <p>В XXI веке давно уже нет нужды называть переменные покороче.</p>
-<ul>
-<li><strong>Плохо</strong>: <code>order.time()</code> — неясно, о каком времени идёт речь: время создания заказа, время готовности заказа, время ожидания заказа?…<br />
-<strong>Хорошо</strong>: <code>order.get_estimated_delivery_time()</code></li>
-<li><strong>Плохо</strong>:
-<code>
-// возвращает положение первого вхождения в строку str2
+<p><strong>Плохо</strong>: <code>order.time()</code> — неясно, о каком времени идёт речь: время создания заказа, время готовности заказа, время ожидания заказа?…</p>
+<p><strong>Хорошо</strong>: <code>order.get_estimated_delivery_time()</code></p>
+<p><strong>Плохо</strong>:</p>
+<pre><code>// возвращает положение первого вхождения в строку str2
 // любого символа из строки str2
 strpbrk (str1, str2)
-</code>
-Возможно, автору этого API казалось, что аббревиатура <code>pbrk</code> что-то значит для читателя, но он явно ошибся. К тому же, невозможно сходу понять, какая из строк <code>str1</code>, <code>str2</code> является набором символов для поиска.<br />
-<strong>Хорошо</strong>: <code>str_search_for_characters (lookup_character_set, str)</code><br />
-Однако необходимость существования такого метода вообще вызывает сомнения, достаточно было бы иметь удобную функцию поиска подстроки с нужными параметрами. Аналогично сокращение <code>string</code> до <code>str</code> выглядит совершенно бессмысленным, но, увы, является устоявшимся для большого количества предметных областей.</li>
-</ul>
+</code></pre>
+<p>Возможно, автору этого API казалось, что аббревиатура <code>pbrk</code> что-то значит для читателя, но он явно ошибся. К тому же, невозможно сходу понять, какая из строк <code>str1</code>, <code>str2</code> является набором символов для поиска.</p>
+<p><strong>Хорошо</strong>: <code>str_search_for_characters (lookup_character_set, str)</code><br />
+— однако необходимость существования такого метода вообще вызывает сомнения, достаточно было бы иметь удобную функцию поиска подстроки с нужными параметрами. Аналогично сокращение <code>string</code> до <code>str</code> выглядит совершенно бессмысленным, но, увы, является устоявшимся для большого количества предметных областей.</p>
 <h4 id="6">6. Тип поля должен быть ясен из его названия</h4>
 <p>Если поле называется <code>recipe</code> — мы ожидаем, что его значением является сущность типа <code>Recipe</code>. Если поле называется <code>recipe_id</code> — мы ожидаем, что его значением является идентификатор, который мы сможем найти в составе сущности <code>Recipe</code>.</p>
-<p>Сущности-массивы должны именоваться во множественном числе или собирательными выражениями — <code>objects</code>, <code>children</code>; если это невозможно (термин неисчисляемый), следует добавить префикс или постфикс, не оставляющий сомнений:</p>
-<ul>
-<li><strong>плохо</strong>: <code>GET /news</code> — неясно, будет ли получена какая-то конкретная новость или массив новостей;
-<strong>хорошо</strong>: <code>GET /news-list</code>.</li>
-</ul>
-<p>Аналогично, если ожидается булево значение, то из названия это должно быть очевидно, т.е. именование должно описывать некоторое качественное состояние, например, <code>is_ready</code>, <code>open_now</code>:</p>
-<ul>
-<li><strong>плохо</strong>: <code>"task.status": true</code> — неочевидно, что статус бинарен, плюс такое API будет нерасширяемым;<br />
-<strong>хорошо</strong>: <code>"task.is_finished": true</code>.</li>
-</ul>
+<p>Сущности-массивы должны именоваться во множественном числе или собирательными выражениями — <code>objects</code>, <code>children</code>; если это невозможно (термин неисчисляемый), следует добавить префикс или постфикс, не оставляющий сомнений.</p>
+<p><strong>Плохо</strong>: <code>GET /news</code> — неясно, будет ли получена какая-то конкретная новость или массив новостей.</p>
+<p><strong>Хорошо</strong>: <code>GET /news-list</code>.</p>
+<p>Аналогично, если ожидается булево значение, то из названия это должно быть очевидно, т.е. именование должно описывать некоторое качественное состояние, например, <code>is_ready</code>, <code>open_now</code>.</p>
+<p><strong>Плохо</strong>: <code>"task.status": true</code> — неочевидно, что статус бинарен, плюс такое API будет нерасширяемым.</p>
+<p><strong>Хорошо</strong>: <code>"task.is_finished": true</code>.</p>
 <p>Отдельно следует оговорить, что на разных платформах эти правила следует дополнить по-своему с учетом специфики first-class citizen-типов. Например, объекты типа <code>Date</code>, если таковые имеются, разумно индицировать с помощью, например, постфикса <code>_at</code> (<code>created_at</code>, <code>occurred_at</code>, etc) или <code>_date</code>.</p>
 <p>Если наименование сущности само по себе является каким-либо термином, способным смутить разработчика, лучше добавить лишний префикс или постфикс, чтобы избежать непонимания.</p>
-<ul>
-<li><strong>Плохо</strong>:
-<code>
-// Возвращает список встроенных функций кофе-машины
-GET /coffee-machines/functions
-</code>
-Слово "functions" многозначное; может означать и встроенные функции, и написанный код, и состояние (функционирует-не функционирует).<br />
-<strong>Хорошо</strong>: <code>GET /v1/coffee-machines/builtin-functions-list</code></li>
-</ul>
+<p><strong>Плохо</strong>:</p>
+<pre><code>// Возвращает список встроенных функций кофе-машины
+GET /coffee-machines/{id}/functions
+</code></pre>
+<p>Слово "functions" многозначное; может означать и встроенные функции, и написанный код, и состояние (функционирует-не функционирует).</p>
+<p><strong>Хорошо</strong>: <code>GET /v1/coffee-machines/{id}/builtin-functions-list</code></p>
 <h4 id="7">7. Подобные сущности должны называться подобно и вести себя подобным образом</h4>
-<ul>
-<li><p><strong>Плохо</strong>: <code>begin_transition</code> / <code>stop_transition</code><br />
-— <code>begin</code> и <code>stop</code> — непарные термины; разработчик будет вынужден рыться в документации.<br />
-<strong>Хорошо</strong>: <code>begin_transition</code> / <code>end_transition</code> либо <code>start_transition</code> / <code>stop_transition</code>.</p></li>
-<li><p><strong>Плохо</strong>:  </p>
+<p><strong>Плохо</strong>: <code>begin_transition</code> / <code>stop_transition</code><br />
+— <code>begin</code> и <code>stop</code> — непарные термины; разработчик будет вынужден рыться в документации.</p>
+<p><strong>Хорошо</strong>: <code>begin_transition</code> / <code>end_transition</code> либо <code>start_transition</code> / <code>stop_transition</code>.</p>
+<p><strong>Плохо</strong>:  </p>
 <pre><code>// Находит первую позицию позицию строки `needle`
 // внутри строки `haystack`
 strpos(haystack, needle)
@@ -705,22 +700,19 @@ str_replace(needle, replace, haystack)
 <ul>
 <li>написание неконсистентно в части знака подчеркивания;</li>
 <li>близкие по смыслу методы имеют разный порядок аргументов <code>needle</code>/<code>haystack</code>; </li>
-<li>первый из методов находит только первое вхождение строки <code>needle</code>, а другой — все вхождения, и об этом поведении никак нельзя узнать из сигнатуры функций.</li></ul>
-<p>Упражнение «как сделать эти интерфейсы хорошо» предоставим читателю.</p></li>
+<li>первый из методов находит только первое вхождение строки <code>needle</code>, а другой — все вхождения, и об этом поведении никак нельзя узнать из сигнатуры функций.</li>
 </ul>
+<p>Упражнение «как сделать эти интерфейсы хорошо» предоставим читателю.</p>
 <h4 id="8">8. Клиент всегда должен знать полное состояние системы</h4>
 <p>Правило можно ещё сформулировать так: не заставляйте клиент гадать.</p>
-<ul>
-<li><strong>Плохо</strong>:
-<code>
-// Создаёт комментарий и возвращает его id
+<p><strong>Плохо</strong>:</p>
+<pre><code>// Создаёт комментарий и возвращает его id
 POST /comments
 { "content" }
 →
 { "comment_id" }
-</code>
-<code>
-// Возвращает комментарий по его id
+</code></pre>
+<pre><code>// Возвращает комментарий по его id
 GET /comments/{id}
 →
 {
@@ -730,64 +722,54 @@ GET /comments/{id}
   "action_required": "solve_captcha",
   "content"
 }
-</code>
-— хотя операция будто бы выполнена успешна, клиенту необходимо сделать дополнительный запрос, чтобы понять необходимость решения капчи. Между вызовами <code>POST /comments</code> и <code>GET /comments/{id}</code> клиент находится в состоянии кота Шрёдингера: непонятно, опубликован комментарий или нет, и как отразить это пользователю.<br />
-<strong>Хорошо</strong>:
-<code>
-// Создаёт комментарий и возвращает его
+</code></pre>
+<p>— хотя операция будто бы выполнена успешна, клиенту необходимо сделать дополнительный запрос, чтобы понять необходимость решения капчи. Между вызовами <code>POST /comments</code> и <code>GET /comments/{id}</code> клиент находится в состоянии кота Шрёдингера: непонятно, опубликован комментарий или нет, и как отразить это пользователю.</p>
+<p><strong>Хорошо</strong>:</p>
+<pre><code>// Создаёт комментарий и возвращает его
 POST /v1/comments
 { "content" }
 →
 { "comment_id", "published", "action_required", "content" }
-</code>
-<code>
-// Возвращает комментарий по его id
+</code></pre>
+<pre><code>// Возвращает комментарий по его id
 GET /v1/comments/{id}
 →
 { /* в точности тот же формат, 
-   что и в ответе POST /comments */
-   …
+    что и в ответе POST /comments */
+    …
 }
-</code>
-Вообще в 9 случаях из 10 (а фактически — всегда, когда размер ответа невелик) во всех отношениях лучше из любой модифицирующей операции возвращать полное состояние сущности в том же формате, что и из операции доступа на чтение.</li>
-</ul>
+</code></pre>
+<p>Вообще в 9 случаях из 10 (а фактически — всегда, когда размер ответа невелик) во всех отношениях лучше из любой модифицирующей операции возвращать полное состояние сущности в том же формате, что и из операции доступа на чтение.</p>
 <h4 id="9">9. Идемпотентность</h4>
-<p>Все эндпойнты должны быть идемпотентны. Напомним, идемпотентность — это следующее свойство: повторный вызов той же операции с теми же параметрами не изменяет результат. Поскольку мы обсуждаем в первую очередь клиент-серверное взаимодействие, узким местом в котором является ненадежность сетевой составляющей, повтор запроса при обрыве соединения — не исключительная ситуация, а норма жизни.</p>
+<p>Все операции должны быть идемпотентны. Напомним, идемпотентность — это следующее свойство: повторный вызов той же операции с теми же параметрами не изменяет результат. Поскольку мы обсуждаем в первую очередь клиент-серверное взаимодействие, узким местом в котором является ненадежность сетевой составляющей, повтор запроса при обрыве соединения — не исключительная ситуация, а норма жизни.</p>
 <p>Там, где идемпотентность не может быть обеспечена естественным образом, необходимо добавить явный параметр — ключ идемпотентности или ревизию.</p>
-<ul>
-<li><strong>Плохо</strong>
-<code>
-// Создаёт заказ
+<p><strong>Плохо</strong>:</p>
+<pre><code>// Создаёт заказ
 POST /orders
-</code>
-Повтор запроса создаст два заказа!</li>
-<li><strong>Хорошо</strong>
-<code>
-// Создаёт заказ
+</code></pre>
+<p>Повтор запроса создаст два заказа!</p>
+<p><strong>Хорошо</strong>:</p>
+<pre><code>// Создаёт заказ
 POST /v1/orders
 X-Idempotency-Token: &lt;случайная строка&gt;
-</code>
-Клиент на своей стороне запоминает X-Idempotency-Token, и, в случае автоматического повторного перезапроса, обязан его сохранить. Сервер на своей стороне проверяет токен и, если заказ с таким токеном уже существует для этого клиента, не даёт создать заказ повторно.<br />
-Альтернатива:
-<code>
-// Создаёт черновик заказа
+</code></pre>
+<p>Клиент на своей стороне запоминает X-Idempotency-Token, и, в случае автоматического повторного перезапроса, обязан его сохранить. Сервер на своей стороне проверяет токен и, если заказ с таким токеном уже существует для этого клиента, не даёт создать заказ повторно.</p>
+<p><strong>Альтернатива</strong>:</p>
+<pre><code>// Создаёт черновик заказа
 POST /v1/orders
 →
 { "draft_id" }
-</code>
-<code>
-// Подтверждает черновик заказа
+</code></pre>
+<pre><code>// Подтверждает черновик заказа
 PUT /v1/orders/drafts/{draft_id}
 { "confirmed": true }
-</code>
-Создание черновика заказа — необязывающая операция, которая не приводит ни к каким последствиям, поэтому допустимо создавать черновики без токена идемпотентности.
-Операция подтверждения заказа — уже естественным образом идемпотентна, для неё <code>draft_id</code> играет роль ключа идемпотентности.</li>
-</ul>
+</code></pre>
+<p>Создание черновика заказа — необязывающая операция, которая не приводит ни к каким последствиям, поэтому допустимо создавать черновики без токена идемпотентности.
+Операция подтверждения заказа — уже естественным образом идемпотентна, для неё <code>draft_id</code> играет роль ключа идемпотентности.</p>
 <h4 id="10">10. Кэширование</h4>
 <p>В клиент-серверном API, как правило, сеть и ресурс сервера не бесконечны, поэтому кэширование на клиенте результатов операции является стандартным действием.</p>
 <p>Желательно в такой ситуации внести ясность; если не из сигнатур операций, то хотя бы из документации должно быть понятно, каким образом можно кэшировать результат.</p>
-<ul>
-<li><p><strong>Плохо</strong></p>
+<p><strong>Плохо</strong>:</p>
 <pre><code>// Возвращает цену лунго в кафе,
 // ближайшем к указанной точке
 GET /price?recipe=lungo&amp;longitude={longitude}&amp;latitude={latitude}
@@ -797,8 +779,10 @@ GET /price?recipe=lungo&amp;longitude={longitude}&amp;latitude={latitude}
 <p>Возникает два вопроса:</p>
 <ul>
 <li>в течение какого времени эта цена действительна?</li>
-<li>на каком расстоянии от указанной точки цена всё ещё действительна?  </li></ul>
-<p>Если на первый вопрос легко ответить введением стандартных заголовков Cache-Control, то для второго вопроса готовых решений нет. В ситуации, когда кэш нужен и по временной, и по пространственной координате следует поступить примерно так:</p>
+<li>на каком расстоянии от указанной точки цена всё ещё действительна?  </li>
+</ul>
+<p><strong>Хорошо</strong>:
+Для указания времени жизни кэша можно пользоваться стандатрными средствами протокола, например, заголовком Cache-Control. В ситуации, когда кэш нужен и по временной, и по пространственной координате следует поступить примерно так:</p>
 <pre><code>// Возвращает предложение: за какую сумму
 // наш сервис готов приготовить лунго
 GET /price?recipe=lungo&amp;longitude={longitude}&amp;latitude={latitude}
@@ -819,13 +803,11 @@ GET /price?recipe=lungo&amp;longitude={longitude}&amp;latitude={latitude}
     }
   }
 }
-</code></pre></li>
-</ul>
+</code></pre>
 <h4 id="11-1">11. Пагинация, фильтрация и курсоры</h4>
 <p>Любой эндпойнт, возвращающий массивы данных, должен содержать пагинацию. Никаких исключений в этом правиле быть не может.</p>
 <p>Любой эндпойнт, возвращающий изменяемые данные постранично, должен обеспечивать возможность эти данные перебрать.</p>
-<ul>
-<li><p><strong>Плохо</strong>:</p>
+<p><strong>Плохо</strong>:</p>
 <pre><code>// Возвращает указанный limit записей,
 // отсортированных по дате создания
 // начиная с записи с номером offset
@@ -843,7 +825,8 @@ GET /records?limit=10&amp;offset=100
 <li>Что произойдёт, если при переборе списка одна из записей в уже перебранной части будет удалена?<br />
 Произойдёт следующее: клиент пропустит одну запись и никогда не сможет об этом узнать.</li>
 <li>Какие параметры кэширования мы можем выставить на этот эндпойнт?<br />
-Никакие: повторяя запрос с теми же limit-offset мы каждый раз получаем новый набор записей.</li></ol>
+Никакие: повторяя запрос с теми же limit-offset, мы каждый раз получаем новый набор записей.</li>
+</ol>
 <p><strong>Хорошо</strong>: в таких однонаправленных списках пагинация должна быть организована по тому ключу, порядок которых фиксирован. Например, вот так:</p>
 <pre><code>// Возвращает указанный limit записей,
 // отсортированных по дате создания,
@@ -858,8 +841,8 @@ GET /records?newer_than={record_id}&amp;limit=10
 </code></pre>
 <p>При такой организации клиенту не надо заботиться об удалении или добавлении записей в уже перебранной части списка: он продолжает перебор по идентификатору известной записи — первой известной, если надо получить новые записи; последней известной, если надо продолжить перебор.
 Если операции удаления записей нет, то такие запросы можно свободно кэшировать — по одному и тому же URL будет всегда возвращаться один и тот же набор записей.<br />
-Другой вариант организации таких списков — возврат курсора <code>cursor</code>, который используется вместо <code>record_id</code>, что делает интерфейсы универсальнее.</p></li>
-<li><p><strong>Плохо</strong>:</p>
+Другой вариант организации таких списков — возврат курсора <code>cursor</code>, который используется вместо <code>record_id</code>, что делает интерфейсы универсальнее.</p>
+<p><strong>Плохо</strong>:</p>
 <pre><code>// Возвращает указанный limit записей,
 // отсортированных по полю sort_by
 // в порядке sort_order,
@@ -898,6 +881,6 @@ GET /v1/record-views/{id}?cursor={cursor}
   "cursor"
 }
 </code></pre>
-<p>Недостатком этой схемы является необходимость заводить отдельные списки под каждый вид сортировки.</p></li></ul></li>
+<p>Недостатком этой схемы является необходимость заводить отдельные списки под каждый вид сортировки, а также появление множества событий для одной записи, если данные меняются часто.</p></li>
 </ul><div class="page-break"></div></article>
 </body></html>