grammar

docs/API.ru.html

@@ -2594,7 +2594,7 @@ try {
 <p>Вместо версий можно использовать дату последней модификации ресурса (что в целом гораздо менее надёжно ввиду неидеальной синхронизации часов в разных узлах системы; не забывайте, как минимум, сохранять дату с максимально доступной точностью!) либо идентификаторы сущности (ETag).</p>
 <p>Достоинством оптимистичного управления параллелизмом является, таким образом, возможность «спрятать» сложную в имплементации и масштабировании часть «под капотом». Недостаток же состоит в том, что ошибки версионирования теперь являются штатным поведением, и клиентам <em>придётся</em> написать правильную работу с ними,  иначе их приложение может вообще оказаться неработоспособным — пользователь будет вечно пытаться создать заказ с неактуальной версией.</p>
 <p><strong>NB</strong>. Выбор ресурса, версию которого мы требуем передать для получения доступа, очень важен. Если в нашем примере мы заведём глобальную версию всей системы, которая изменяется при поступлении любого заказа, то, очевидно, у пользователя будут околонулевые шансы успешно разместить заказ.</p><div class="page-break"></div><h3><a href="#api-patterns-weak-consistency" class="anchor" id="api-patterns-weak-consistency">Глава 18. Слабая консистентность</a><a href="#chapter-18" class="secondary-anchor" id="chapter-18"> </a></h3>
-<p>Описанный в предыдущей главе подход фактически представляет собой размен производительности API на «нормальный» (т.е. ожидаемый) фон ошибок при работе с ним путём изоляции компонента, отвечающего за строгую консистентность и управление параллелизмом внутри системы. Тем не менее, его пропускная способность всё равно ограничена, и снизить её мы можем единственным образом — убрав строгую консистентность из внешнего API, что даст возможность осуществлять чтение состояния системы из реплик:</p>
+<p>Описанный в предыдущей главе подход фактически представляет собой размен производительности API на «нормальный» (т.е. ожидаемый) фон ошибок при работе с ним путём изоляции компонента, отвечающего за строгую консистентность и управление параллелизмом внутри системы. Тем не менее, его пропускная способность всё равно ограничена, и увеличить её мы можем единственным образом — убрав строгую консистентность из внешнего API, что даст возможность осуществлять чтение состояния системы из реплик:</p>
 <pre><code>// Получаем состояние,
 // возможно, из реплики
 const orderState = 

docs/index.html

@@ -10,7 +10,7 @@
     </title>
     <meta
         name="description"
-        content="API-first development is one of the hottest technical topics nowadays since many companies started to realize that API serves as a multiplicator to their opportunities—but it also amplifies the design mistakes as well. This book is written to share the expertise and describe the best practices in designing and developing APIs. It comprises six sections dedicated to: the API design, API patterns, maintaining backwards compatibility, HTTP API & REST, SDK and UI libraries, API product management."
+        content="API-first development is one of the hottest technical topics nowadays since many companies started to realize that API serves as a multiplicator to their opportunities—but it also amplifies the design mistakes as well. This book is written to share the expertise and describe the best practices in designing and developing APIs. It comprises six sections dedicated to: the API design, API patterns, maintaining backward compatibility, HTTP API & REST, SDK and UI libraries, API product management."
     />
     <meta property="og:type" content="article" />
     <meta
@@ -19,7 +19,7 @@
     />
     <meta
         property="og:description"
-        content="API-first development is one of the hottest technical topics nowadays since many companies started to realize that API serves as a multiplicator to their opportunities—but it also amplifies the design mistakes as well. This book is written to share the expertise and describe the best practices in designing and developing APIs. It comprises six sections dedicated to: the API design, API patterns, maintaining backwards compatibility, HTTP API & REST, SDK and UI libraries, API product management."
+        content="API-first development is one of the hottest technical topics nowadays since many companies started to realize that API serves as a multiplicator to their opportunities—but it also amplifies the design mistakes as well. This book is written to share the expertise and describe the best practices in designing and developing APIs. It comprises six sections dedicated to: the API design, API patterns, maintaining backward compatibility, HTTP API & REST, SDK and UI libraries, API product management."
     />
     <meta property="og:image" content="assets/header.png" />
     <meta
@@ -46,7 +46,7 @@
 <p>This book is written to share the expertise and describe the best practices in designing and developing APIs. It comprises six sections dedicated to:</p>
 <ul><li>— The API design</li>
 <li>— API patterns</li>
-<li>— Backwards compatibility</li>
+<li>— Backward compatibility</li>
 <li>— HTTP API & REST</li>
 <li>— SDK and UI libraries</li>
 <li>— API product management.</ul>
@@ -62,7 +62,7 @@
 <li><a href="API.en.html#intro-api-solutions-overview">Chapter 3. Overview of Existing API Development Solutions</a></li>
 <li><a href="API.en.html#intro-api-quality">Chapter 4. API Quality Criteria</a></li>
 <li><a href="API.en.html#intro-api-first-approach">Chapter 5. The API-first approach</a></li>
-<li><a href="API.en.html#intro-back-compat">Chapter 6. On Backwards Compatibility</a></li>
+<li><a href="API.en.html#intro-back-compat">Chapter 6. On Backward Compatibility</a></li>
 <li><a href="API.en.html#intro-versioning">Chapter 7. On Versioning</a></li>
 <li><a href="API.en.html#intro-terms-notation">Chapter 8. Terms and Notation Keys</a></li>
                             </ul>
@@ -95,9 +95,9 @@
                             </ul>
             </li>
 <li>
-                <h4><a href="API.en.html#section-4">Section III. The Backwards Compatibility</a></h4>
+                <h4><a href="API.en.html#section-4">Section III. The Backward Compatibility</a></h4>
                 <ul>
-                    <li><a href="API.en.html#back-compat-statement">Chapter 26. The Backwards Compatibility Problem Statement</a></li>
+                    <li><a href="API.en.html#back-compat-statement">Chapter 26. The Backward Compatibility Problem Statement</a></li>
 <li><a href="API.en.html#back-compat-iceberg-waterline">Chapter 27. On the Waterline of the Iceberg</a></li>
 <li><a href="API.en.html#back-compat-abstracting-extending">Chapter 28. Extending through Abstracting</a></li>
 <li><a href="API.en.html#back-compat-strong-coupling">Chapter 29. Strong Coupling and Related Problems</a></li>

src/en/clean-copy/02-Section I. The API Design/05.md

@@ -850,7 +850,7 @@ X-Idempotency-Token: <token>
 
 — the server found out that a different token was used in creating revision 124, which means an access conflict.
 
-Furthermore, adding idempotency tokens not only resolves the issue but also makes advanced optimizations possible. If the server detects an access conflict, it could try to resolve it, “rebasing” the update like modern version control systems do, and return a `200 OK` instead of a `409 Conflict`. This logic dramatically improves user experience, being fully backwards compatible, and helps to avoid conflict-resolving code fragmentation.
+Furthermore, adding idempotency tokens not only resolves the issue but also makes advanced optimizations possible. If the server detects an access conflict, it could try to resolve it, “rebasing” the update like modern version control systems do, and return a `200 OK` instead of a `409 Conflict`. This logic dramatically improves user experience, being fully backward-compatible, and helps to avoid conflict-resolving code fragmentation.
 
 Also, be warned: clients are bad at implementing idempotency tokens. Two problems are common:
   * you can't really expect clients generate truly random tokens — they may share the same seed or simply use weak algorithms or entropy sources; therefore you must put constraints on token checking: token must be unique to a specific user and resource, not globally;

src/en/clean-copy/04-Section III. The Backward Compatibility/01.md

@@ -6,7 +6,7 @@ Backward compatibility is a feature of the entire API system to be stable in tim
 
   1. What does “functionally correctly” mean?
 
-      It means that the code continues to serve its function, i.e., to solve some users' problems. It doesn't mean it continues working indistinguishably from the previous version: for example, if you're maintaining a UI library, changing functionally insignificant design details like shadow depth or border stroke type is backwards compatible, whereas changing the sizes of the visual components is not.
+      It means that the code continues to serve its function, i.e., to solve some users' problems. It doesn't mean it continues working indistinguishably from the previous version: for example, if you're maintaining a UI library, changing functionally insignificant design details like shadow depth or border stroke type is backward-compatible, whereas changing the sizes of the visual components is not.
 
   2. What does “a long period of time” mean?
 
@@ -76,7 +76,7 @@ The nastiest thing here is that not only does incremental progress in a form of
 
 In the case of the API-first approach, the backward compatibility problem gets one more dimension: the specification and code generation based on it. It becomes possible to break backward compatibility without breaking the spec (let's say by introducing eventual consistency instead of the strict one) — and vice versa, modify the spec in a backwards-incompatible manner changing nothing in the protocol and therefore not affecting existing integrations at all (let's say, by replacing `additionalProperties: false` with `true` in OpenAPI).
 
-The question of whether two specification versions are backwards compatible or not rather belongs to a gray zone, as specification standards themselves do not define this. Generally speaking, the “specification change is backwards-compatible” statement is equivalent to “any client code written or generated based on the previous version of the spec continues working correctly after the API vendor releases the new API version implementing the new version of the spec.” Practically speaking, following this definition seems quite unrealistic for two reasons: it's impossible to learn the behavior of every piece of code-generating software there (for instance, it's rather hard to say whether code generated based on a specification that includes the parameter `additionalProperties: false` will still function properly if the server starts returning additional fields).
+The question of whether two specification versions are backward-compatible or not rather belongs to a gray zone, as specification standards themselves do not define this. Generally speaking, the “specification change is backward-compatible” statement is equivalent to “any client code written or generated based on the previous version of the spec continues working correctly after the API vendor releases the new API version implementing the new version of the spec.” Practically speaking, following this definition seems quite unrealistic for two reasons: it's impossible to learn the behavior of every piece of code-generating software there (for instance, it's rather hard to say whether code generated based on a specification that includes the parameter `additionalProperties: false` will still function properly if the server starts returning additional fields).
 
 Thus, using IDLs to describe APIs with all advantages it undeniably brings to the field, leads to having one more side to the technology drift problem: the IDL version and, more importantly, versions of helper software based on it, are constantly and sometimes unpredictably evolving.
 

src/v1/en/clean-copy/02-Section I. The API Design/05.md

@@ -851,7 +851,7 @@ X-Idempotency-Token: <token>
 ```
 — the server found out that a different token was used in creating revision 124, which means an access conflict.
 
-Furthermore, adding idempotency tokens not only resolves the issue but also makes advanced optimizations possible. If the server detects an access conflict, it could try to resolve it, “rebasing” the update like modern version control systems do, and return a `200 OK` instead of a `409 Conflict`. This logic dramatically improves user experience, being fully backwards compatible, and helps to avoid conflict-resolving code fragmentation.
+Furthermore, adding idempotency tokens not only resolves the issue but also makes advanced optimizations possible. If the server detects an access conflict, it could try to resolve it, “rebasing” the update like modern version control systems do, and return a `200 OK` instead of a `409 Conflict`. This logic dramatically improves user experience, being fully backward-compatible, and helps to avoid conflict-resolving code fragmentation.
 
 Also, be warned: clients are bad at implementing idempotency tokens. Two problems are common:
   * you can't really expect clients generate truly random tokens — they may share the same seed or simply use weak algorithms or entropy sources; therefore you must put constraints on token checking: token must be unique to a specific user and resource, not globally;

src/v1/en/clean-copy/03-Section II. The Backward Compatibility/01.md

@@ -6,7 +6,7 @@ Backward compatibility is a feature of the entire API system to be stable in tim
 
   1. What does “functionally correctly” mean?
 
-      It means that the code continues to serve its function, i.e., to solve some users' problems. It doesn't mean it continues working indistinguishably from the previous version: for example, if you're maintaining a UI library, changing functionally insignificant design details like shadow depth or border stroke type is backwards compatible, whereas changing the sizes of the visual components is not.
+      It means that the code continues to serve its function, i.e., to solve some users' problems. It doesn't mean it continues working indistinguishably from the previous version: for example, if you're maintaining a UI library, changing functionally insignificant design details like shadow depth or border stroke type is backward-compatible, whereas changing the sizes of the visual components is not.
 
   2. What does “a long period of time” mean?