Introduction translation complete

docs/API.en.html

@@ -134,5 +134,49 @@ h4, h5 {
 <p>Of course, large companies which occupy firm market positions could afford implying such a taxation. Furthermore, they may introduce penalties for those who refuse to adapt their code to new API versions, up to disabling their applications.</p>
 <p>From our point of view such practice cannot be justified. Don't imply hidden taxes on your customers. If you're able to avoid breaking backwards compatibility — never break it.</p>
 <p>Of course, maintaining old API versions is sort of a tax either. Technology changes, and you cannot foresee everything, regardless of how nice your API is initially designed. At some point keeping old API versions results in an inability to provide new functionality and support new platforms, and you will be forced to release new version. But at least you will be able to explain to your customers why they need to make an effort.</p>
-<p>We will discuss API lifecycle and version policies in Section II.</p><div class="page-break"></div><h2>The API Design</h2></article>
+<p>We will discuss API lifecycle and version policies in Section II.</p><div class="page-break"></div><h3 id="chapter5onversioning">Chapter 5. On versioning</h3>
+<p>Here and throughout we firmly stick to <a href="https://semver.org/">semver</a> principles of versioning:</p>
+<ol>
+<li>API versions are denoted with three numbers, i.e. <code>1.2.3</code>.</li>
+<li>First number (major version) when backwards incompatible changes in the API are shipped.</li>
+<li>Second Number (minor version) increases when new functionality is added to the API, keeping backwards compatibility intact.</li>
+<li>Third number (patch) increases when new API version contains bug fixes only.</li>
+</ol>
+<p>Terms ‘major API version’ and ‘new API version, containing backwards incompatible changes to functionality’ are therefore to be considered as equivalent.</p>
+<p>In Section II we will discuss versioning policies in more details. In Section I we will just use semver versions designation, specifically <code>v1</code>, <code>v2</code>, etc.</p><div class="page-break"></div><h3 id="chapter6termsandnotationkeys">Chapter 6. Terms and Notation Keys</h3>
+<p>Software development is being characterized, among other things, by an existence of many different engineering paradigms, whose adepts sometimes are quite aggressive towards other paradigms' adepts. While writing this book we are deliberately avoiding using terms like ‘method’, ‘object’, ‘function’, and so on, using a neutral term ‘entity’ instead. ‘Entity’ means some atomic functionality unit, like class, method, object, monad, prototype (underline what you think right).</p>
+<p>For entity's components we regretfully failed to find a proper term, so we will use words ‘fields’ and ‘methods’.</p>
+<p>Most of the examples of APIs in general will be provide in a form of JSON-over-HTTP endpoints. This is some sort of notation which, as we see it, helps to describe concepts in the most comprehensible manner. <code>GET /v1/orders</code> endpoint call could easily be replaced with <code>orders.get()</code> method call, local or remote. JSON could easily be replaced with any other data format. Meaning of assertions shouldn't change.</p>
+<p>Let's take a look at the following example:</p>
+<pre><code>// Method description
+POST /v1/bucket/{id}/some-resource
+X-Idempotency-Token: &lt;idempotency token&gt;
+{
+  …
+  // This is a single-line comment
+  "some_parameter": "example value",
+  …
+}
+→ 404 Not Found
+Cache-Control: no-cache
+{
+  /* And this is
+     a multiline comment */
+  "error_message"
+}
+</code></pre>
+<p>It should be read like:</p>
+<ul>
+<li>perform a POST-request to a <code>/v1/bucket/{id}/some-resource</code> resource, where <code>{id}</code> is to be replaced with some <code>bucket</code>'s identifier <code>{something}</code> should refer to the nearest term from the left, unless explicitly specified otherwise);</li>
+<li>a specific <code>X-Idempotency-Token</code> header is added to the request alongside with standard headers (which we omit);</li>
+<li>terms in angle brackets (<code>&lt;idempotency token&gt;</code>) describe the semantic of an entity value (field, header, parameter);</li>
+<li>a specific JSON, containing a <code>some_parameter</code> field with <code>example value</code> value and some other unspecified fields (indicated by ellipsis) is being sent as a request body payload;</li>
+<li>in response (marked with arrow symbol <code>→</code>) server returns a <code>404 Not Founds</code> status code; status might be omitted (treat it like <code>200 OK</code> if no status is provided);</li>
+<li>response could possibly contain additional notable headers;</li>
+<li>response body is a JSON comprising single <code>error_message</code> field; field value absence means that field contains exactly what you expect it should contain — some error message in this case.</li>
+</ul>
+<p>Some request and response parts might be omitted if they are irrelevant to a topic being discussed.</p>
+<p>Simplified notation might be used to avoid redundancies, like <code>POST /v1/bucket/{id}/some-resource</code> <code>{…,"some_parameter",…}</code> → <code>{ "operation_id" }</code>; request and response bodies might also be omitted.</p>
+<p>We will be using expressions like ‘<code>POST /v1/bucket/{id}/some-resource</code> method’ (or simply ‘<code>bucket/some-resource</code> method’, ‘<code>some-resource</code>’ method if no other <code>some-resource</code>s are specified throughout the chapter, so there is no ambiguity) to refer to such endpoint definition.</p>
+<p>Apart from HTTP API notation we will employ C-style pseudocode, or, to be more precise, JavaScript-like or Python-like since types are omitted. We assume such imperative structures being readable enough to skip detailed grammar explanations.</p><div class="page-break"></div><h2>The API Design</h2></article>
     </body></html>

src/en/clean-copy/01-Introduction/05.md

@@ -0,0 +1,11 @@
+### On versioning
+
+Here and throughout we firmly stick to [semver](https://semver.org/) principles of versioning:
+  1. API versions are denoted with three numbers, i.e. `1.2.3`.
+  1. First number (major version) when backwards incompatible changes in the API are shipped.
+  2. Second Number (minor version) increases when new functionality is added to the API, keeping backwards compatibility intact.
+  3. Third number (patch) increases when new API version contains bug fixes only.
+
+Terms ‘major API version’ and ‘new API version, containing backwards incompatible changes to functionality’ are therefore to be considered as equivalent.
+
+In Section II we will discuss versioning policies in more details. In Section I we will just use semver versions designation, specifically `v1`, `v2`, etc.

src/en/clean-copy/01-Introduction/06.md

@@ -0,0 +1,45 @@
+### Terms and Notation Keys
+
+Software development is being characterized, among other things, by an existence of many different engineering paradigms, whose adepts sometimes are quite aggressive towards other paradigms' adepts. While writing this book we are deliberately avoiding using terms like ‘method’, ‘object’, ‘function’, and so on, using a neutral term ‘entity’ instead. ‘Entity’ means some atomic functionality unit, like class, method, object, monad, prototype (underline what you think right).
+
+For entity's components we regretfully failed to find a proper term, so we will use words ‘fields’ and ‘methods’.
+
+Most of the examples of APIs in general will be provide in a form of JSON-over-HTTP endpoints. This is some sort of notation which, as we see it, helps to describe concepts in the most comprehensible manner. `GET /v1/orders` endpoint call could easily be replaced with `orders.get()` method call, local or remote. JSON could easily be replaced with any other data format. Meaning of assertions shouldn't change.
+
+Let's take a look at the following example:
+
+```
+// Method description
+POST /v1/bucket/{id}/some-resource
+X-Idempotency-Token: <idempotency token>
+{
+  …
+  // This is a single-line comment
+  "some_parameter": "example value",
+  …
+}
+→ 404 Not Found
+Cache-Control: no-cache
+{
+  /* And this is
+     a multiline comment */
+  "error_message"
+}
+```
+
+It should be read like:
+  * perform a POST-request to a `/v1/bucket/{id}/some-resource` resource, where `{id}` is to be replaced with some `bucket`'s identifier `{something}` should refer to the nearest term from the left, unless explicitly specified otherwise);
+  * a specific `X-Idempotency-Token` header is added to the request alongside with standard headers (which we omit);
+  * terms in angle brackets (`<idempotency token>`) describe the semantic of an entity value (field, header, parameter);
+  * a specific JSON, containing a `some_parameter` field with `example value` value and some other unspecified fields (indicated by ellipsis) is being sent as a request body payload;
+  * in response (marked with arrow symbol `→`) server returns a `404 Not Founds` status code; status might be omitted (treat it like `200 OK` if no status is provided);
+  * response could possibly contain additional notable headers;
+  * response body is a JSON comprising single `error_message` field; field value absence means that field contains exactly what you expect it should contain — some error message in this case.
+
+Some request and response parts might be omitted if they are irrelevant to a topic being discussed.
+
+Simplified notation might be used to avoid redundancies, like `POST /v1/bucket/{id}/some-resource` `{…,"some_parameter",…}` → `{ "operation_id" }`; request and response bodies might also be omitted.
+
+We will be using expressions like ‘`POST /v1/bucket/{id}/some-resource` method’ (or simply ‘`bucket/some-resource` method’, ‘`some-resource`’ method if no other `some-resource`s are specified throughout the chapter, so there is no ambiguity) to refer to such endpoint definition.
+
+Apart from HTTP API notation we will employ C-style pseudocode, or, to be more precise, JavaScript-like or Python-like since types are omitted. We assume such imperative structures being readable enough to skip detailed grammar explanations.