The-API-Book/docs/index.html


<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/png" href="assets/favicon.png" />
    <title>
        Sergey Konstantinov. The API
    </title>
    <meta
        name="description"
        content="Designing APIs is a very special skill: API is a multiplier to both your opportunities and mistakes. This book is written to share the expertise and describe the best practices in the API design. In Section I, we'll discuss designing APIs as a concept: how to build the architecture properly, from high-level planning down to final interfaces. Section II is dedicated to expanding existing APIs in a backwards-compatible manner."
    />
    <meta property="og:type" content="article" />
    <meta
        property="og:title"
        content="Sergey Konstantinov. The API"
    />
    <meta
        property="og:description"
        content="Designing APIs is a very special skill: API is a multiplier to both your opportunities and mistakes. This book is written to share the expertise and describe the best practices in the API design. In Section I, we'll discuss designing APIs as a concept: how to build the architecture properly, from high-level planning down to final interfaces. Section II is dedicated to expanding existing APIs in a backwards-compatible manner."
    />
    <meta property="og:image" content="assets/header.png" />
    <meta
        property="og:url"
        content="https://github.com/twirl/The-API-Book"
    />
    <link rel="stylesheet" href="assets/landing.css"/>
</head>
<body>
    <nav>
        <img
            class="header"
            src="assets/header.jpg"
            alt="Sergey Konstantinov. The API"
        /><br />
        <h1>Sergey Konstantinov<br/><span class="title">The API</span></h1>
        <h2>Free e-book</h2>
        <br />Subscribe for updates on <a class="github" href="https://github.com/twirl/The-API-Book"></a>
        <br/>Follow me on <a class="linkedin" href="https://www.linkedin.com/in/twirl/"></a> &middot; <a class="twitter" href="https://twitter.com/blogovodoved"></a> &middot; <a class="medium" href="https://twirl.medium.com/">Medium</a>
        <br />Support this work on <a class="patreon" href="https://www.patreon.com/yatwirl">Patreon</a> &middot; <a class="kindle" href="https://www.amazon.com/gp/product/B09RHH44S5/ref=dbs_a_def_rwt_hsch_vapi_tkin_p1_i0">buy Kindle version</a>
        <br />⚙️⚙️⚙️
    </nav>
    <p>The 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.</p>
<p>This book is dedicated to designing APIs: how to build the architecture properly, from a high-level planning down to final interfaces, and to extend API in a backwards-compatible manner.</p>
<p>Illustration &amp; inspiration: <a href="https://www.instagram.com/art.mari.ka/">art.mari.ka</a>.</p>
    <p>You might download ‘The API’ in <a href="API.en.pdf">PDF</a>, <a href="API.en.epub">EPUB</a>, or <a href="API.en.html">read it online</a>.
    </p>
    <h3>Table of Contents</h3>
    <ul><li>
                <h4><a href="API.en.html#section-1">Introduction</a></h4>
                <ul>
                    <li><a href="API.en.html#chapter-1">Chapter 1. On the Structure of This Book</a></li>
<li><a href="API.en.html#chapter-2">Chapter 2. The API Definition</a></li>
<li><a href="API.en.html#chapter-3">Chapter 3. API Quality Criteria</a></li>
<li><a href="API.en.html#chapter-4">Chapter 4. Backwards Compatibility</a></li>
<li><a href="API.en.html#chapter-5">Chapter 5. On Versioning</a></li>
<li><a href="API.en.html#chapter-6">Chapter 6. Terms and Notation Keys</a></li>
                            </ul>
            </li>
<li>
                <h4><a href="API.en.html#section-2">Section I. The API Design</a></h4>
                <ul>
                    <li><a href="API.en.html#chapter-7">Chapter 7. The API Contexts Pyramid</a></li>
<li><a href="API.en.html#chapter-8">Chapter 8. Defining an Application Field</a></li>
<li><a href="API.en.html#chapter-9">Chapter 9. Separating Abstraction Levels</a></li>
<li><a href="API.en.html#chapter-10">Chapter 10. Isolating Responsibility Areas</a></li>
<li><a href="API.en.html#chapter-11">Chapter 11. Describing Final Interfaces</a></li>
<li><a href="API.en.html#chapter-12">Chapter 12. Annex to Section I. Generic API Example</a></li>
                            </ul>
            </li>
<li>
                <h4><a href="API.en.html#section-3">Section II. The Backwards Compatibility</a></h4>
                <ul>
                    <li><a href="API.en.html#chapter-13">Chapter 13. The Backwards Compatibility Problem Statement</a></li>
<li><a href="API.en.html#chapter-14">Chapter 14. On the Waterline of the Iceberg</a></li>
<li><a href="API.en.html#chapter-15">Chapter 15. Extending through Abstracting</a></li>
<li><a href="API.en.html#chapter-16">Chapter 16. Strong Coupling and Related Problems</a></li>
<li><a href="API.en.html#chapter-17">Chapter 17. Weak Coupling</a></li>
<li><a href="API.en.html#chapter-18">Chapter 18. Interfaces as a Universal Pattern</a></li>
<li><a href="API.en.html#chapter-19">Chapter 19. The Serenity Notepad</a></li>
                            </ul>
            </li>
<li>
                <h4>Section III. The API Product</h4>
                <ul>
                    <li>Chapter 20. API as a Product</li>
<li>Chapter 21. API Business Models</li>
<li>Chapter 22. Developing a Product Vision</li>
<li>Chapter 23. Communicating with Developers</li>
<li>Chapter 24. Communicating with Business Owners</li>
<li>Chapter 25. API Services Range</li>
<li>Chapter 26. API Key Performance Indicators</li>
<li>Chapter 27. Identifying Users and Preventing Fraud</li>
<li>Chapter 28. IT-security</li>
<li>Chapter 29. Supporting API users</li>
<li>Chapter 30. Documentation</li>
<li>Chapter 31. Testing Environment</li>
<li>Chapter 32. Managing Expectations</li>
                            </ul>
            </li>
    </ul>
    <p>This book is distributed under the <a href="http://creativecommons.org/licenses/by-nc/4.0/">Creative Commons Attribution-NonCommercial 4.0 International licence</a>.</p>
    <p>Source code available at <a href="https://github.com/twirl/The-API-Book">github.com/twirl/The-API-Book</a></p>
    <h3><a name="about-author">About the Author</a></h3>
    <section class="about-me">
        <aside><img src="https://konstantinov.cc/static/me.png"/></aside>
        <div class="content">
        <p>Sergey Konstantinov has been working with APIs for more than a decade. He started his career as a software engineer in the Maps API division at Yandex and eventually became the head of the service, being responsible for both technical architecture and product management.</p>
<p>During this tenure, Sergey got a unique experience in building world-class APIs with a daily audience of tens of millions, planning roadmaps for such a service, and giving numerous public speeches. He also worked for a year and a half as a member of the W3C Technical Architecture Group.</p>
<p>After nine years in Maps, Sergey switched to technical-lead roles in other departments and companies, leading integration efforts and being responsible for the technical architecture of entire business units. Today, Sergey lives in Tallinn, Estonia, and works as a staff software engineer at Bolt.</p></div>
    </section>
    <p>Книгу «API» можно <a href="index.ru.html">читать по-русски</a>.</p>
</body>
</html>
new build script 2022-07-07 00:41:03 +03:00
Landing Page 2022-06-23 23:28:55 +03:00			`<!DOCTYPE html>`
			`<html>`
new build script 2022-07-07 00:41:03 +03:00			`<head>`
			`<meta charset="utf-8" />`
			`<meta name="viewport" content="width=device-width, initial-scale=1" />`
small build fixes + fresh build 2022-07-10 23:34:14 +03:00			`<link rel="icon" type="image/png" href="assets/favicon.png" />`
new build script 2022-07-07 00:41:03 +03:00			`<title>`
			`Sergey Konstantinov. The API`
			`</title>`
			`<meta`
			`name="description"`
			`content="Designing APIs is a very special skill: API is a multiplier to both your opportunities and mistakes. This book is written to share the expertise and describe the best practices in the API design. In Section I, we'll discuss designing APIs as a concept: how to build the architecture properly, from high-level planning down to final interfaces. Section II is dedicated to expanding existing APIs in a backwards-compatible manner."`
			`/>`
			`<meta property="og:type" content="article" />`
			`<meta`
			`property="og:title"`
			`content="Sergey Konstantinov. The API"`
			`/>`
			`<meta`
			`property="og:description"`
			`content="Designing APIs is a very special skill: API is a multiplier to both your opportunities and mistakes. This book is written to share the expertise and describe the best practices in the API design. In Section I, we'll discuss designing APIs as a concept: how to build the architecture properly, from high-level planning down to final interfaces. Section II is dedicated to expanding existing APIs in a backwards-compatible manner."`
			`/>`
			`<meta property="og:image" content="assets/header.png" />`
			`<meta`
			`property="og:url"`
			`content="https://github.com/twirl/The-API-Book"`
			`/>`
About author 2022-07-31 15:08:37 +03:00			`<link rel="stylesheet" href="assets/landing.css"/>`
new build script 2022-07-07 00:41:03 +03:00			`</head>`
			`<body>`
			`<nav>`
			`<img`
About author 2022-07-31 15:08:37 +03:00			`class="header"`
new build script 2022-07-07 00:41:03 +03:00			`src="assets/header.jpg"`
			`alt="Sergey Konstantinov. The API"`
			`/><br />`
			`<h1>Sergey Konstantinov<br/><span class="title">The API</span></h1>`
			`<h2>Free e-book</h2>`
			`<br />Subscribe for updates on <a class="github" href="https://github.com/twirl/The-API-Book"></a>`
			`<br/>Follow me on <a class="linkedin" href="https://www.linkedin.com/in/twirl/"></a> · <a class="twitter" href="https://twitter.com/blogovodoved"></a> · <a class="medium" href="https://twirl.medium.com/">Medium</a>`
			`<br />Support this work on <a class="patreon" href="https://www.patreon.com/yatwirl">Patreon</a> · <a class="kindle" href="https://www.amazon.com/gp/product/B09RHH44S5/ref=dbs_a_def_rwt_hsch_vapi_tkin_p1_i0">buy Kindle version</a>`
			`<br />⚙️⚙️⚙️`
			`</nav>`
			`<p>The 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.</p>`
			`<p>This book is dedicated to designing APIs: how to build the architecture properly, from a high-level planning down to final interfaces, and to extend API in a backwards-compatible manner.</p>`
About author 2022-07-31 15:08:37 +03:00			`<p>Illustration & inspiration: <a href="https://www.instagram.com/art.mari.ka/">art.mari.ka</a>.</p>`
new build script 2022-07-07 00:41:03 +03:00			`<p>You might download ‘The API’ in <a href="API.en.pdf">PDF</a>, <a href="API.en.epub">EPUB</a>, or <a href="API.en.html">read it online</a>.`
			`</p>`
			`<h3>Table of Contents</h3>`
			`<ul><li>`
			`<h4><a href="API.en.html#section-1">Introduction</a></h4>`
Landing Page 2022-06-23 23:28:55 +03:00			`<ul>`
new build script 2022-07-07 00:41:03 +03:00			`<li><a href="API.en.html#chapter-1">Chapter 1. On the Structure of This Book</a></li>`
			`<li><a href="API.en.html#chapter-2">Chapter 2. The API Definition</a></li>`
			`<li><a href="API.en.html#chapter-3">Chapter 3. API Quality Criteria</a></li>`
			`<li><a href="API.en.html#chapter-4">Chapter 4. Backwards Compatibility</a></li>`
			`<li><a href="API.en.html#chapter-5">Chapter 5. On Versioning</a></li>`
			`<li><a href="API.en.html#chapter-6">Chapter 6. Terms and Notation Keys</a></li>`
			`</ul>`
Landing Page 2022-06-23 23:28:55 +03:00			`</li>`
new build script 2022-07-07 00:41:03 +03:00			`<li>`
			`<h4><a href="API.en.html#section-2">Section I. The API Design</a></h4>`
Landing Page 2022-06-23 23:28:55 +03:00			`<ul>`
new build script 2022-07-07 00:41:03 +03:00			`<li><a href="API.en.html#chapter-7">Chapter 7. The API Contexts Pyramid</a></li>`
			`<li><a href="API.en.html#chapter-8">Chapter 8. Defining an Application Field</a></li>`
			`<li><a href="API.en.html#chapter-9">Chapter 9. Separating Abstraction Levels</a></li>`
			`<li><a href="API.en.html#chapter-10">Chapter 10. Isolating Responsibility Areas</a></li>`
			`<li><a href="API.en.html#chapter-11">Chapter 11. Describing Final Interfaces</a></li>`
			`<li><a href="API.en.html#chapter-12">Chapter 12. Annex to Section I. Generic API Example</a></li>`
			`</ul>`
Landing Page 2022-06-23 23:28:55 +03:00			`</li>`
new build script 2022-07-07 00:41:03 +03:00			`<li>`
			`<h4><a href="API.en.html#section-3">Section II. The Backwards Compatibility</a></h4>`
Landing Page 2022-06-23 23:28:55 +03:00			`<ul>`
new build script 2022-07-07 00:41:03 +03:00			`<li><a href="API.en.html#chapter-13">Chapter 13. The Backwards Compatibility Problem Statement</a></li>`
Fresh build 2022-08-08 00:25:17 +03:00			`<li><a href="API.en.html#chapter-14">Chapter 14. On the Waterline of the Iceberg</a></li>`
new build script 2022-07-07 00:41:03 +03:00			`<li><a href="API.en.html#chapter-15">Chapter 15. Extending through Abstracting</a></li>`
			`<li><a href="API.en.html#chapter-16">Chapter 16. Strong Coupling and Related Problems</a></li>`
			`<li><a href="API.en.html#chapter-17">Chapter 17. Weak Coupling</a></li>`
			`<li><a href="API.en.html#chapter-18">Chapter 18. Interfaces as a Universal Pattern</a></li>`
			`<li><a href="API.en.html#chapter-19">Chapter 19. The Serenity Notepad</a></li>`
			`</ul>`
Landing Page 2022-06-23 23:28:55 +03:00			`</li>`
new build script 2022-07-07 00:41:03 +03:00			`<li>`
			`<h4>Section III. The API Product</h4>`
Landing Page 2022-06-23 23:28:55 +03:00			`<ul>`
			`<li>Chapter 20. API as a Product</li>`
new build script 2022-07-07 00:41:03 +03:00			`<li>Chapter 21. API Business Models</li>`
			`<li>Chapter 22. Developing a Product Vision</li>`
			`<li>Chapter 23. Communicating with Developers</li>`
			`<li>Chapter 24. Communicating with Business Owners</li>`
			`<li>Chapter 25. API Services Range</li>`
			`<li>Chapter 26. API Key Performance Indicators</li>`
			`<li>Chapter 27. Identifying Users and Preventing Fraud</li>`
			`<li>Chapter 28. IT-security</li>`
			`<li>Chapter 29. Supporting API users</li>`
			`<li>Chapter 30. Documentation</li>`
			`<li>Chapter 31. Testing Environment</li>`
			`<li>Chapter 32. Managing Expectations</li>`
			`</ul>`
Landing Page 2022-06-23 23:28:55 +03:00			`</li>`
new build script 2022-07-07 00:41:03 +03:00			`</ul>`
			`<p>This book is distributed under the <a href="http://creativecommons.org/licenses/by-nc/4.0/">Creative Commons Attribution-NonCommercial 4.0 International licence</a>.</p>`
			`<p>Source code available at <a href="https://github.com/twirl/The-API-Book">github.com/twirl/The-API-Book</a></p>`
About author 2022-07-31 15:08:37 +03:00			`<h3><a name="about-author">About the Author</a></h3>`
			`<section class="about-me">`
			`<aside><img src="https://konstantinov.cc/static/me.png"/></aside>`
			`<div class="content">`
			`<p>Sergey Konstantinov has been working with APIs for more than a decade. He started his career as a software engineer in the Maps API division at Yandex and eventually became the head of the service, being responsible for both technical architecture and product management.</p>`
			`<p>During this tenure, Sergey got a unique experience in building world-class APIs with a daily audience of tens of millions, planning roadmaps for such a service, and giving numerous public speeches. He also worked for a year and a half as a member of the W3C Technical Architecture Group.</p>`
			`<p>After nine years in Maps, Sergey switched to technical-lead roles in other departments and companies, leading integration efforts and being responsible for the technical architecture of entire business units. Today, Sergey lives in Tallinn, Estonia, and works as a staff software engineer at Bolt.</p></div>`
			`</section>`
			`<p>Книгу «API» можно <a href="index.ru.html">читать по-русски</a>.</p>`
new build script 2022-07-07 00:41:03 +03:00			`</body>`
			`</html>`